Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number

Writing Good Documentation

by defyance (Curate)
on Jun 24, 2002 at 17:51 UTC ( #176871=perlmeditation: print w/replies, xml ) Need Help??

Until recently, I haven't written anything for real production use. A few beta apps, personal use shell scripts and such. Now I have a few things that I'm fixing to release, and good documentation will be needed. In viewing some other nodes about writing documentation, I'm sure I have a good idea of what I need to do, sum it up in a professional manner that is easy to understand. I have written HOW TO's and README's before, but never full fledged documentation. I'm sure your probably thinking; What is there to it? You write a useful documentation on what you did, and the functions of the program. However, IMHO, the art of writing good doc's to back up your work is as much of an art as the code itself.

What I really want to get from this post is your thoughts on writing good documentation. Stuff from this could be compiled to make a useful tutorial. So please hit me with your knowledge/opinions!

P.S. In addition to wanting to hear what you think about writing Doc's, I'd also like to hear what you think about a Tutorial on the subject.

perl -e '$a="3567"; $b=hex($a); printf("%2X\n",$a);'

Replies are listed 'Best First'.
Re: Writing Good Documentation
by tjh (Curate) on Jun 24, 2002 at 18:25 UTC
    These may look like generalist issues, but they're really a list of gripes I've had about documentation I was trying to depend on, as well as on documentation I've participated in creating :)

    • Carefully choose the viewpoint from which you write. In practice, this means to me that it's important to inspect what you assume from your readers. Who's the audience? etc. In my experience, docs assuming a relatively extreme tech reader usually fails, since no two readers have the same education or experience. It's also dangerous to assume that the author's education is the standard the docs are written to as well.

      Not that I think it should pander to illiterates or uneducated, but I think there are ways to make docs plainly readable, and understandable, for just about everyone.

    • Regardless of the the assumed audience, compose in readable, possibly Reader's Digest style, language. I know that'll get me flamed in some quarters, but docs endure and what's common knowledge or practice now may not be so this time next year.

    • Good overview as a lead, including examples and some various times when the product|module could|would be used.

    • Index thoroughly, including related keywords. If you use jargon others may not understand (now or in the future), they may not find what they need.

    • If the releases are modules or other tools, be very clear in the docs about the params into, and output of, each method or sub.

    • It's irksome to read the docs of modules that are written for a specialty field, and not really be able to quickly discern that. Be sure it's clear almost from the very beginning, what field or other specialty it applies to.

    • Rewrite...rewrite...rewrite

    • Get reviews, just like code reviews.

    • Version the docs as religiously as you version the product.

    • It's ok to have the docs have personality and some personalization. Pronouns are ok...

    Have fun!


      These are all valid points and are generally good to follow. However, one should also look down at how much time has been alotted to documenting your product. In my experience, I was never able to apply all of the above mentioned points completely due to time constraints imposed by various factors (management being one of them ;). Although, documentation is a very important piece, in practice there's not always enough time to finish it off.

      Thus, a few suggestions as to how you might save time all the while produce sufficient documentation.

      • Write your documentation as you move through your project. Project managers sometimes overlook the need for allowing extra time to add documentation to a working code. Most often, they are reluctant to do so when you are all done and the product seems to work just fine (especially in the Web environment, the project is simply closed with too little documentation). However, if you were to ask for a little bit more time during the coding phase (write it off on various factors if you don't really want to disclose the detailed facts), they'll normally give in and thereby provide you with ample room to fit adequate documentation.

      • Write your documentation to look perfect (as much as you possible can) the first time. I know, I know! It is not always possible and I'm nuts for suggesting it, but what I'm saying is at least make it a 'point' to drive at. This will reduce the time you'll have to spend to hack at poorly written/organized documentation.

      • This leads to the next point... Organize your documentation, always! ;). A good documentation outline will normally lead to a well written documentation with minimal time spent writing it.

      # Under Construction
      • Get reviews, just like code reviews.

      This is one of the best ways to be sure your documentation will properly reach its audience. In my experience, it's been best to have at least one person not directly associated with the project review the docs, if possible. Sometimes that's the only way I've realized that one of my assumptions about How The Universe Works is neither common knowledge nor an immutable law of physics. ;)


Re: Writing Good Documentation
by japhy (Canon) on Jun 24, 2002 at 19:04 UTC
    A recent gripe I've uncovered from looking at the docs of a very large application whose development team I've recently joined...

    When documenting the args to a function, do not use a scalar in the place of a reference to something. It throws people (like me) off. =item $obj->add_kids($kids)
    should be =item $obj->add_kids(\@kids)
    And the function's name should represent the ability to take more than one child. If it were named add_kid, I'd go nuts. Honestly.

    Jeff[japhy]Pinyan: Perl, regex, and perl hacker, who'd like a job (NYC-area)
    s++=END;++y(;-P)}y js++=;shajsj<++y(p-q)}?print:??;

Re: Writing Good Documentation
by screamingeagle (Curate) on Jun 24, 2002 at 18:32 UTC
    One should write documentation in a way that it is clear to everyone , not just oneself...put yourself in another programmer's position, who has no idea what the code does, or what its dependencies are. IMHO, it is better to be overly descriptive than to blindly assume a certain level of knowledge on the readers' part.

    It's also helpful to make a template document initially, and then make each following documentation page follow the same structure of the template page. This ensures consistency.

    A few sections which would be included in every document would be :
    a) Purpose of Program: what the code's primary purpose is
    b) Database tables used/affected by code
    c) Perl Modules (specify exact versions of Perl Modules) required for the code to work
    d) Include files used
    e) Command-line Parameters passed to the script

    I would also recommend completing the documentation within a couple of days of finishing up the final version of your code, cause you would still have everything fresh in your mind...i find that i forget 99% of what i did within a week of completing a project ;-) ...of course, the best approach would be to document the code as you go. HTH
Re: Writing Good Documentation
by ignatz (Vicar) on Jun 24, 2002 at 19:27 UTC
    The one thing that there is almost never enough of is examples. Simple examples... complex examples... complete working examples... If it's got a feature, don't just "document" it, show us an example. If there's more than one way to do something, show us an example of each. No amount of verbage can replace a good working example. In fact, if you have to choose between writing long paragraphs describing in detail the reasons behind each design decision or writing a few good examples, write the examples.

    Did I mention that I like examples?

      Totally agreed. This is what set Perl apart for me, compared to other languages. When I first started using perl, and found the help system, it very nearly blew my little mind. I was left staring at the screen going "easy.. too.. use... can't.. cope.. Whoopee!".

      This is after struggling with horrible C documentation like

      5. Go to the src subdirectory and look at the top of topten.c. You m +ay want to change the definitions of PERSMAX and PERS_IS_UID here to get d +ifferent behavior from the high score list. 6. Edit the top sections of the src and util Makefiles. (If you are +doing a full recompile, or if you got your files from someplace besides +the official distribution, type 'touch makedefs.c' to make sure certai +n files (onames.h, pm.h) get remade instead of relying on the potentially troublesome timestamps.)

      Thesedays all my code comes with examples, and where possible, a base configuration that will work on nearly all machines.

      I didn't believe in evil until I dated it.

      Absolutely 100% agreed. I cannot go forth from documentation written by someone who assumes the verbage provided gives enough information in one place to make good use of it. Learning Perl is my one prime example, the documentation provided (once you're used to the semantics) is indispensible, but at times confusing, the examples provided are excellent but may not apply to the issue at hand. I found myself trying to find definitions for words used in the documentation. Feeling completely at odds with it, I found Perl Monks and the rest is history.

      Examples of any kind are your friend, supply novice, intermediate and expert examples then try to mix it up. This may make your documentation larger but I think it would appeal to a larger audience.

        I've been very impressed with the way Bruce Eckel deals with it in his books. All of the examples are automatically built so that he can veryify that they actually compile.

        Makes me start to think about a test/example system where the examples of a script are also some of it's tests. That way as you change your code the tests don't just point out errors in code but also where you need to update your examples to reflect changes in the code. Hmmmm.......

Re: Writing Good Documentation
by cjf (Parson) on Jun 24, 2002 at 21:14 UTC
Re: Writing Good Documentation
by maverick (Curate) on Jun 24, 2002 at 19:20 UTC
    Take the wisdom of the previous posters :) in addition you could try this technique that I've used before. It does seem to yield better docs (...either that or I just suck at writing :) ).

    If I wrote the program, I understand it. Granted I can try my best to put myself in the shoes of another and write the docs occordingly. But let's face it...there's no substitute for having someone else (who has not been involved with the project) read your docs and try to follow them to install/configure/use the program.

    When they hit a snag, explain to them what to do and have *them* update the docs. Odds are it will be more thorough and clearer than the update you would have made.


    OmG! They killed tilly! You *bleep*!!

Re: Writing Good Documentation
by BazB (Priest) on Jun 24, 2002 at 20:29 UTC

    Just a couple of short points.

    First up: use your own documentation.
    Try and use every feature as you've described it in the docs - I find I sometimes miss a piece of functionality in the docs (or even the code) if I'm in a hurry.
    Have your colleagues/friends use the code using only the documentation, not verbal tips :-)

    Depending on the complexity of the system (and the skill of the document's author), I've also found that a number of increasingly more detailed sections can be of great help. I don't want to have to read the whole 100 pages of the document to know how enough about how the system works to begin to follow it.
    Good diagrams can also help - a picture says a thousand words...

    As already mentioned, good examples are one of the most useful pieces of the whole document.
    Showing how to solve the problem the code was written for using an example or two can make sense of several pages of more in-depth options, methods or sub-commands.

    Update: Oh, and if no-one ever uses the docs, best find out why: either you have built the best piece of software ever, or the docs are rubbish :-)


Re: Writing Good Documentation
by tomhukins (Curate) on Jun 24, 2002 at 19:39 UTC
Re: Writing Good Documentation
by theorbtwo (Prior) on Jun 24, 2002 at 19:15 UTC

    Several people have already made the point not to use too much jargon or specialty knowlage in your documentation. But if you can't do that (because you don't feel like, or don't have the time to, explain what your module/program does in lay terms, or because you simply aren't that good of a writer), at least explain where the terminology you use /is/ documented, preferably on the web. For example, I'm (attempting to) write a module to nicely parse MIDL files into parameter lists for Win32::COM (which I don't link to because I havn't finished writing it). Now, I'm not going to explain all of MIDL's syntax and keywords, because I don't feel like repeating Microsoft's and the OMG's documentation on the matter, but also because some of it simply isn't very relevant, and some I don't even understand fully -- I just attempt to cleanly ignore. So, in my documentation (which I've only just begun to write), I make a lot of references. It isn't exactly a /good/ thing, but it's better then the alternitive.

    We are using here a powerful strategy of synthesis: wishful thinking. -- The Wizard Book

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://176871]
Approved by FoxtrotUniform
Front-paged by hsmyers
[marto]: they still don't know there was a problem, nobody told them! :P
[Corion]: marto: Ow! I would assume there is a cron job monitoring the free disk space and automatically opening a ticket at 90%, 95% and 100% usage...
[Corion]: Even we had automatic emails back when we maintained the machine ourselves...
[marto]: Corion you under estimate how lazy these admins are :P
[Discipulus]: we too; using opsview alarms
[marto]: the key word: outsourcing ;)
[Corion]: marto: Yeah, feels like that ;) You could set up the cronjob that auto-creates tickets :-))
[marto]: the ticketing system does not accept calls via email, nor has it a working API. It's tied into Active Directory for authentication and the Solaris boxes aren't on that domain
[Corion]: The one thing I haven't figured out a solution to is how to get an edge-trigger instead of sending an email every 5 minutes if the usage is above 90%. I want one mail when it goes over 90% but no more emails as long as it stays between 90% and 95%.
[Corion]: marto: Clever! ;)

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (9)
As of 2017-01-24 10:08 GMT
Find Nodes?
    Voting Booth?
    Do you watch meteor showers?

    Results (203 votes). Check out past polls.