Dist::Zilla Does Pod

So it is POD day here in the Dist-Pen.

I am not going two write up another POD tutorial as there are tons of those about what today's post-ette
is about what happened when you start writing up your POD.

What I always like to do in the POD process is start writing it at about the very same time when I am coding things up and fill in most of the banks as I go along. Others are of the do it at the beginning and others are wait for the end. So I guess I take the middle ground.

I have worked on both ends of the spectrum.

In one shop you could not check anything into the source repository unless it was documented. Myself I was quite diligent and did do all the required documentation. Until I found out that the other nine developers where just putting in the absolute minimum for documentation, which was worse than no documentation IMHO. We got away with this as no one ever checked the documentation after it was in the repository.

On the other end how about a 3rd party API I was involved in some 60K+ lines of code and the only documentation provided was a two line copyright notice and a six page print out of the function names.

One thing I am proud of is that all of my Modules on CPAN have proper documentation and most if it comes out my simple do little bits as you go methodology.

To end my process I go back and do a review of what I have done and try to read it as a first time user. This usually results in to things;

First better documentation. I will usually move things about or add in sections to help explain what is going on.

Second things I forgot to add into the system.

Today for example I added in a 'Usage Outline' to better explain what Accessor does and how it is to be uses and today I also decided that I need to add in a method that will return a list of the available DADs.

That's it for today. A short and almost useless post I know but here is a cute kittenpicture as compensation.


Leave a comment

About byterock

user-pic Long time Perl guy, a few CPAN mods allot of work on DBD::Oracle and a few YAPC presentations