Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

How to write documentation?

by ajt (Prior)
on Oct 18, 2001 at 12:43 UTC ( #119629=perlmeditation: print w/ replies, xml ) Need Help??

Hi all, this question may seem basic, and obvious, but I couldn't find anything useful on SuperSearch.

I'm involved in a web project and I'm writing stuff to glue it together. In the event of me being squashed by a bus tomorrow, I want my employer to be able to use what I've written, and fix/extend it with time.

At the moment there are no other Perl or web people in the team, the project is an out growth of the SAP team. With time there will be non-technical users as well, but barring an unfortunate incident with a bus, I don't expect the permenant Perl/Apache/Web team ever to grow beyond me.

What kind of documents are useful? I need to document the project so people can use it and extend/fix it, so I assume I need at least two kinds of docs: technical and user.

Every script I write is commented and had POD, obviously, but that's not much use to most people at the moment. At every change as I go along, I print out hard copy, and file it, generate HTML from POD, as well as archiving it.

I'm also building an intranet "how-to" users guide as I go along, with examples and user instructions. I'm not a technical writer, and as everyone knows it's easy to forget to mention something that you as the author knows..

So my questions:

What strategies have monks found helpful in their projects, both user and tech docs?

When you inherited projects, what helped you carry on?

Any books or web sites to suggest for small projects of this nature?

As ever, humble thanks in advance...

Comment on How to write documentation?
Re: How to write documentation?
by arhuman (Vicar) on Oct 18, 2001 at 13:34 UTC
    For my part I tend to write documentation as I write code :
    I wrote a general (abstract) documentation, then I add more detailed parts.
    (then I iterate the second phase until satisfied).

    Note that you can do it
    • In the same document
      Taking care to put the simple abstract part at the beginning and hiding as much as possible the too specifics details (in an APPENDIX for example)
    • In several documents
      This allow you to specialize your documentation to the reader
      (Beccause a techie don't need the same informations as a commercial...)
    The second way is my favourite way, I usually make a (very) small doc describing the product
    (just to make the reader understand what we're talking about)
    I then write a more detailed document with links to several other (specialized) docs (Appendix, user guide, maintenance guide, sysadmin's guide, developper's guide...).
    document.

    Last note: 'the quick install' and 'common troubleshooting' parts seems to me the most used part of a technical docs
    (at least at my office), it may be worthy to write them with a special care...

    UPDATE : The 'links/resources' part is also a must write to my mind...

    UPDATE 2: As I realize that my answer may be far from practical, I'll add some common useful guidelines :
    • Write a READABLE way
      Otherwise nobody will (be able to) use it...
    • Adapt your text to your reader (the content AND the form)
    • Don't forget your initial goal
      your technical doc shouldn't become a technical rant about how good the solution is...In the same vein in a commercial documentation, it's totally useless to explain your over-smart technical hack, speak about technological advance ;-)
    • Use spell checkers (It's VERY important for some people (usually your bosses ;-))
    • Use a portable format to allow other people to work on your documentation, convert it...

    "Only Bad Coders Code Badly In Perl" (OBC2BIP)
Re: How to write documentation?
by pjf (Curate) on Oct 18, 2001 at 13:56 UTC
    G'day ajt,

    It sounds like you're already got a great start with the whole documentation thing. The following isn't really advice, it's more a relating of my own experience and what's worked for me.

    User Documentation
    I've tended to prefer to use a version management system such as CVS rather than making hard-copies at every stage. With CVS it's very easy to see the difference between versions, to track who made which changes and when, and to maintain multiple branches of the software if necessary. Of course, CVS does have a bit of a learning curve, and non-technical people take quite some time to get used to it, even with a graphical interface.

    For user documentation, I've found the best way is to get a user to write it. Seriously. There'll be things which neither yourself nor your fellow developers will think to document, simply because they're so obvious you'll never think of them. I've been at workplaces where the user documentation was always written by non-technical people for that very reason.

    Documentation is like software in many ways, in that it also needs to be tested. The best people to test are those who aren't already familiar with the software, and haven't had you drop a previous copy of the user manual on their desk. I always exist my test population much too quickly. ;)

    Technical Documentation
    For technical documentation, find a document that you find really useful, and copy the layout. POD is fabulous for tech docs because you can have the documentation sitting next to the code it refers too -- nobody can lose the documentation or be too busy to look it up.

    I try to document every function -- what it's purpose is, an y bugs or unexpected behaviour it might have, and an example of use if it's not immediately obvious. Good, clean code is often self-documenting, and that's certainly something worth aiming for.

    Each file should also (at a minimum) have some header documentation stating the purpose of the file, when it was written, and who by. This means someone can quickly and easily find if they're in the right place without having to look at code.

    Keeping an FAQ is also very useful. Usually the same questions keep appearing again and again. These are obviously things you want to document.

    Cheers,
    Paul

      Just as an aside, I also subscribe to having the users write their own documentation.
      This has numerous advantages:
      • They gleen a more formal understanding of your solution to the problem
      • Its more likely to be complete -> not missing 'coder-obvious' elements
      • Its 100% technical-jargon-free!
      • You dont have to do it yourself!
      Of course, am sure you could generate a framework template from your code for them to fill in (:
      the 'qif;
Re: How to write documentation?
by Malkavian (Friar) on Oct 18, 2001 at 16:42 UTC
    Sounds like you've got a good start to the documentation in writing the POD documentation for each program your write..
    There are a few things I usually do that mean if something happens to me, then everything is maintainable..
    • First comes the POD, to allow a man-page like overview of the functionality of the script. Anyone reading this is assumed to be technically literate, and likely to either be reverse engineering your whole system or developing it further.
    • Next comes the internal comments to the code. I always have the functions seperated from the rest of the code quite visibly. Each of the functions is domment described as to what arguments it expects, what it does, and what it returns. This means anyone skimming through your code can treat functions as 'black boxes'.. This greatly speeds someone's understanding of just what your code does.
    • Next comes the 'HOWTO'. This is a rough guide to the dataflow of the system. What datasources you have, and what datasinks. What programs do what, and why. Also, where you keep things like temp files, and any bits that may need cleaning in case of serious system failure... Basically, this is a guide to keeping things working without having to know just what the system is doing.. It's there to give someone time to understand the true intricacies.
    • As time goes on, it's a good move to have a proper user guide on the go. This should be a detailed version of the 'HOWTO' dealing with all the data munging that you perform, how the seperate scripts interact, examples, and just about everything you can think of to detail the system.
    As, in my current job, I've taken over a system coded by many people in many languages (C, Perl, Bash, Csh etc), all with little to no documentation, I think that the biggest problems I had were lack of any HOWTO, or overview of what the system was doing, where it threw temp files, what it could and couldn't handle, and which scripts dealt with which area (no, there was no distinct bin dir.. All the code was spread across about 20 different bin dirs, most not obvious).
    This meant that I had to read each script (again, not documented), and work out each function (if it was even split into functions). Needless to say, it was a painful task.
    So, in order of importance, I'd say it would have to be:
    1. A generic HOWTO to enable a random technical person, with skills in Perl/Apache to keep the system alive, and give them a few pointers to maintenance without going too much into specifics. This will at least give them time to lear the system without the world falling apart around theirs ears.
    2. The POD documentation. This is a wonderful aid to letting people get a good view of what the system as a whole is really doing, and learn it rapidly.
    3. The internal comments. This is great to allow people to use your internal APIs you develop, and re-use your code when they develop later.
    4. The in depth user manual is the icing on the cake that walks people through everything... It's good to have, but, without having the above steps complete, it'll likely be lacking in vital areas, that usually get picked on when you do the above docs.

    When you ask what keep me going on in this project I inherited?? Well, lots of caffeine and bloody mindedness spring to mind.
    The parts I've re-written all follow the steps I've mentioned above, and what took me weeks to work out, reading the source, I've had others picking up in hours reading my docs. Which is exactly what I've been aiming for.

    The last stage, after I get all the above done, is a little more light-hearted.. I take to wearing a teeshirt with the big letters "RTFM" on it.. Then I get back to doing the next thing, without having to spend more time away from my code fielding answers that are already in the documentation now. :)

    Hope this helped some,

    Malk
Re (tilly) 1: How to write documentation?
by tilly (Archbishop) on Oct 18, 2001 at 18:50 UTC
    Two thoughts.

    The first is that one way to document is to strive to make as little as possible worth documenting. What do I mean by that? Well suppose you write a script, and it has a bunch of dependencies. What is good is if you can make it have as few installation dependencies as possible, and make those as clear as possible. Then you don't have very much to document about how to install it!

    The second is to consider ways of combining user documentation and specs. An extreme is the approach that Microsoft has been known to take, of actually writing the user documentation as a spec. Somewhat less extreme is the approach of writing down "use cases" for a spec (this is advocated by extreme programming, among other schools). When you have done that, the use cases are extremely suggestive about what to put into the user documentation.

Re: How to write documentation?
by Hutta (Scribe) on Oct 18, 2001 at 20:36 UTC
    If you happen to be hit by a bus, chances are that no matter how clearly and completely you write the text of your documentation, an emergency situation will come up before your (hopefully more bus-resistant replacement) will be able to read it all.

    That isn't to say that you shouldn't bother writing it... By all means, you should.

    I'm a strong proponent of application flow diagrams. In a pinch, it's much easier to see which other things the little picture of 'sqldb19' has lines running to, than to scan through pages of text, hoping that you don't miss a reference to 'sqldb10-20.'

    Note that sqldb19 doesn't need to be a seperate server for this to work. I apply this type of graphical overview to things like cron jobs that summarize data, to be able to know which reports will be wrong if suddenly the cron jobs all stop. It's easy to trace the lines to the sql server, then to the web servers that query it.

    Eh, I tend to be pretty visual, so maybe this is just me...
      I really like a flow diagram. I usually have two documents, one with the flow diagram and the other (that has a version as part of the filename) with version control as the first section (who did what and when and in what version and for who). The rest of the document is a descriprion of how the system works. Something brief, that a developer would understand aside from the introduction which is clear to all.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://119629]
Approved by root
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (15)
As of 2014-11-26 18:57 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My preferred Perl binaries come from:














    Results (172 votes), past polls