byterock

Another boring day in the POD-pen

I am getting sick of writing up PO of well necessary evil I guess at least my post will be sort for the next few days.

Today I managed to get my methods and attributes all written up but that left me with a layout dilemma that I have to solve. Should I go with the very traditional POD alphabetical grouping like this

• Methods
• add_condition
• add_element
• add_filter
• add_gather
• add_link
• add_sort
• create
• delete
• new
• retrieve
• update
• Attributes
• available_drivers
• conditions
• delete_requires_condition
• dynamic_conditions
• dynamic_elements
• dynamic_filters
• dynamic_gathers
• available_drivers
• dynamic_links
• dynamic_sorts
• elements
• ...

No need to put up all the attributes up there as the list goes on a bit.

At first glance it looks ok but if I was interested in the 'elements' attribute I would have to look in at least three different places to gather all the info I may need.

My present 'Elements' entry looks something like this

elements (RO) ARRAY-REF

An array ref of Element, Param, Function or Expression classes that are passed to the underlying DAD. ...

Not even four words into the write up and I now have four more things to look up. With none of these on the list above as they are not attributes or methods. Not the best type of Pod if I want people to actually use Accessor.

Overall I find the above approach rather disjointed, things you expect to be together, say the four CRUD methods are apart. You also ask yourself the question right off the bat, why are there 'add_' methods shouldn't the attribute accessors take care of that??

With the traditional approach to POD there is no introduction to the working concepts behind Accessor, a user is just left dazed and confused.

So out with traditional POD and in with something a little more creative to get my point across.

What I have in mind is the Functional/Manual style this

• Introduction
• Quickstart
• The API
• View
• Elements
• …