Laufeyjarson writes…

The Best Practices suggest breaking your documentation apart by audience.  Different audiences need different documentation.  It then goes on to suggest where this different documentation belongs… and that’s why my opinion diverges.

I do agree that different users need different documentation, and that storing it in different places is a fine idea.  The suggestion made to use external POD files for external documentation doesn’t work well for me. My first strike against it is that POD is awkward to write.  I haven’t used WordStar in years, and here we are, marking text up with special line headers in 2015.  My second strike against it is that it’s hard to find.  People have to know about perldoc to get to it and that keeps a lot of people away.  Third problem is a distribution one; what POD is shipped and how?  Different packaging tools will do different things.  Fourth is that if it’s all in POD, how do you know if it’s internal documentation, user documentation, or design docs?

I prefer to see design docs stored somewhere the development team can all access them and where there is a document history.  I’ve successfully used several different tools for this, including word-processors, wikis and Microsoft OneNote.  (OneNote is sort of a unique thing.  I wish EverNote did a few key parts, but it’s a pale imitation of OneNote.)  I like to see something to support design that handles charts, graphs, and hyperlinks better than POD does.  POD can do most of that, but it’s hard to do.

User documentation needs to be easily accessed.  Today that means HTML or PDF files.  POD and man pages are great for the few real command-line folks left, but most users are living in the GUI and want to click stuff.  The big project I am part of at $WORK uses pod for all the command line option documentation – about two dozen POD files, one for each major verb on the command line, and some extras – and it’s a huge hassle.  We wind up having to maintain docs in at least two places – the command line, and the website.

Reference documentation for the modules and programs themselves needs to be in the code, as I wrote before.

If your users are all programmers, putting it all in the perldoc might work, but I haven’t been in that position in a very long time.

This entry was posted on Thursday, March 19th, 2015 at 8:37 pm and is filed under Perl, Perl Best Practices. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.