Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer
 
PerlMonks  

creating documentation

by stonecolddevin (Parson)
on Dec 27, 2005 at 11:17 UTC ( #519297=perlquestion: print w/replies, xml ) Need Help??

stonecolddevin has asked for the wisdom of the Perl Monks concerning the following question:

Hey all,

I'm continuing my most likely life long quest in creating semi-complex and well featured community/message board software and i've come across this quandary: how does one create documenation for their software?

I don't mean just POD, and I don't mean just how, but what is the best method? Obviously you need to tell what key methods do, how to set it up, copyright, etc. but what else does good documentation need? Examples, yes, but how does one keep it easy reading so as to not lose the reader that's not a systems programmer or a computer guru? Not to mention, cover all the bases.

If this seems stupid or already answered, please blame my percoset and it being 4:17 am.

Thanks in advance!!!

meh.

Replies are listed 'Best First'.
Re: creating documentation
by tirwhan (Abbot) on Dec 27, 2005 at 11:41 UTC

    I've found that a good method is to tell your users that you would dearly love to hear any questions they may have and then answer those questions in your documentation (as well as directly). If someone says "How does it all fit together", add a diagram. If they say "I don't understand what this object/method/button does" add a paragraph on why the thing is there (incidentally, this is also a great time to ask yourself the same question and remove/modify the thing if you find you don't know the answer). If some question keeps coming up despite the fact that you think you've already answered it in the docs, move the explanation into a more prominent place or clarify it.

    The problem with this approach is that you really have to work hard at soliciting user comments. Most people don't like asking questions which can make them appear stupid. So something that appears blatantly obvious to you may not be so obvious to other people but you may never find out because they are too embarrassed to ask. Another obstacle is inertia and unwillingness to explore. So really make it extra clear that you love questions and want to hear them from your users pretty-please with sugar on top.

    Another important thing is to separate your documentation according to target audience, a board user will need different docs from an administrator from a developer from a board owner. Having to wade through stuff that doesn't concern them will turn people off the docs.


    A computer is a state machine. Threads are for people who can't program state machines. -- Alan Cox
Re: creating documentation
by john_oshea (Priest) on Dec 27, 2005 at 11:42 UTC

    An option, if you can arrange it, would be to get someone else to write it. Seriously. If you can find someone who's (a) good at writing, and (b) amenable to helping, then get them to set the system up and document what they're doing at the same time (with your assistance as and when they need it). Ideally, get more than one person to set the system up, so you cover as many 'gotchas' as possible.

    And, yes, I realise that that "If you can find someone..." sentence may possibly be a tad optimistic ;-)

    Another alternative, which I personally think works really well, is to have either a Wiki or user-commentable documentation (see AnnoCPAN for the sort of thing I'm on about). Admittedly it can be more long-term work in terms of keeping the content useful and/or spam-free, but, assuming your users are in any way "involved" with the system, then that may work really well for you.

      john_oshea's first suggestion really hits home.

      As the developer, one "knows" what one builds into the package, but some of the features you include may be obscure to the various users he mentioned... whether because your descriptions -- as accurate as they may be -- don't "ring any bells" for some of them or whether your docs fail to spell out some feature or capability that's obvious to you but doesn't occur to them.

      And even if you can't find the writer he described, watching and coaching others thru the setup/use may greatly improve the documentation, as might the wiki approach, though I would fear that most contributions there would come from the more technically-inclined, leaving some end-user questions unanswered.

Re: creating documentation
by jhourcle (Prior) on Dec 27, 2005 at 13:52 UTC

    I completely agree w/ john_oshea and tirwhan. It is very difficult to write good documentation, as I've said before, but not quite so eloquently.

    To handle trying to write docs for multiple audiences -- sometimes, you need to just write multiple sets of documentation. Eg, it makes sense to place normal usage info in the POD, while placing information about hacking the code in line comments within the program.

    For those times when I've had to write documentation for end users, there are two methods that work best for me -- flesh it out based on questions asked by the users, but even better is to write the documentation before you write any code.

    As strange as it may sound, it's sort of like using XP techniques -- instead of writing tests first, you explain how the program is expected to work ... and from there, you write examples, which get turned into test cases ... and then you write the code.

    It lets you think about how your program / module / whatever fits within a larger system ... it also forces you to try to keep the interfaces simple, so that you can more easily document them. (resulting in it being friendlier software for people to use, typically.)

    As for covering all of the basis -- use some of the module templates, and look at the different sections they have, or look at documentation for similar applications. Documentation is never really done, as you'll always have the trickle in of questions, and you refine the documentation to clarify things (hopefully without making other things more confusing in the process)

      "multiple sets" indeed.

      The famous book Code Complete, which I just started on, talks about scaling software, and mentions that we now build software systems as economically large as building a highrise building.

      On projects of THAT size, some project planning tools will spit out an estimate that you will need 59 different TYPES of documentation.

      And they are right.

      As things get bigger, you are going to need more and more TYPES of document. But just go with it... as long as it is accurate, it doesn't really matter how much you have.

      Each type of documentation is going to have it's own issues.

      With API POD docs, I find I now religiously document the return values for every single method.

      For the main body, I go for elegant SYNOPSISs without too much confusing details, and that I wouldn't mind seeing in real code (because some annoyingly large percentage of people will just cut and paste your SYNOPSIS and modify it to suit their needs)

      If I need diagrams, I just add a doc section. I find myself just piling files into it that I think will be useful, from visio diagrams to the "documentation" of XMLSpy to whatever I think might be useful later.

      Even on small client projects, you'll be looking at 5-10 different types of documentation. Just remember to try and deal with them individually. What is the best way to write user docs, given they are stupid. Screencasts? Text Manuals? PDF Manuals?

      What is the best way to write internal comments... API docs, etc etc.

      You should be able to codify some sort of best practises for the different types of docs one at a time at your company with a bit of experience.
Re: creating documentation
by planetscape (Chancellor) on Dec 27, 2005 at 15:34 UTC

    One tool I especially like is DoxyFilt* (Doxygen for Perl).

    These nodes might also help if you are searching for tools:


    Analyzing large Perl code base.
    Becoming familiar with a too-big codebase?

    This might sound like stating the bleeding obvious, but make certain the examples in your Synopsis actually work... I've run across my fair share that don't.

    Also, in most cases, your user wants output (maybe this doesn't apply precisely to your case, but here goes anyway) - if it's non-obvious how to get output from your program, specify how to do it. Some modules I've come across have specialized print functions... some have really obscure methods... don't force your user to use Data::Dumper on likely-looking variables from your POD in vain attempts to get results.

    HTH,

    * Update: 2005-12-28 Kudos to both john_oshea and tfrayner for alerting me to the fact that my link above has been rendered usless by the foul creatures known as spammers... I have found what appears to be a good link to obtain DoxyFilt; the most recent version seems to be from August 24, 2005: Doxygen-0.84.tar.gz. Thanks again, guys!

    planetscape
      Hi,

      I've seen DoxyFilt recommended here before, but the wiki link you gave here seems to have been spammed with random drug ads for some time. There's an old version available still, but is there a new link for the project?

      Cheers,
      Tim

        Thanks for the reply. The sharp-eyed john_oshea also caught this one... I am currently checking to see what I can find on DoxyFilt, because it is, IMHO, a valuable addition to one's toolbox. I'll post back here with my results. :-)

        HTH,

        Update: 2005-12-28 Kudos to both john_oshea and tfrayner for alerting me to the fact that my link above has been rendered usless by the foul creatures known as spammers... I have found what appears to be a good link to obtain DoxyFilt; the most recent version seems to be from August 24, 2005: Doxygen-0.84.tar.gz. Thanks again, guys!

        planetscape
Re: creating documentation
by leocharre (Priest) on Dec 27, 2005 at 13:49 UTC

    I think the most important thing to sepparate here is you from the percs. Do not code on downers. It may impair your ability to drive a computer or a network and it may have serious mental side effects risks for you and your users.

    Please consider aderall (under 5 mg at any moment in your bloostream), cylert (under 12.7 mg in your bloodstream at any moment please), caffeine (your call), nicotine (your call)- instead.

        Dihydrogen Monoxide can also be very dangerous:

        Unfortunately, I am addicted to dihydrogen monoxide. I got hooked at a very young age, and now I simply can't live without it. The withdrawal symptoms are horrible, and if prolonged, could be fatal. Take my advice - if you're not already hooked on the stuff, stay away from it. Once you start, you'll be hooked for the rest of your life. There is no known treatment.

      Did you ever code better on any drug - be it legal or not, strong or soft? Just curious, because from my experience, plain soberness and enough sleep is simply best for coding...
      Not that I would condemn recreational drug use entirely, especially caffein and nicotine dontīt distract from coding that much and are even quite socially accepted - but drugs wonīt help much solving the problems at hand either. Especially if you are procrastinating on the creation of some usefull but dull documentation.
      (just to get back on topic) ;)

        I'm replying to this and putting it in the meditations section.

Re: creating documentation
by astaines (Curate) on Dec 28, 2005 at 00:20 UTC

    Important preliminary question - Who are your intended audience?

    • You, and maybe the other core developers e.g. Maple
    • Other programmers using your elegant library or your lovely module e.g. libkdepim or DBI
    • Other people installing your cooooool system e.g. Apache, Slashcode
    • Normal techy people using the software e.g. R
    • Normal non-techy people e.g. OpenOffice

    These groups need very different documentation. To produce good documentation you need to know your users. Perhaps the only common thing is that they all need and will benefit from copious annotated examples!

    -- Anthony Staines
Re: creating documentation
by ajt (Prior) on Dec 28, 2005 at 10:06 UTC

    Good question. I asked the same thing many moons ago - I think you will find some of the answers in that thread. I also found that I didn't get the answers I was looking for.

    In the time between then and now, I'd say one thing I have found definitive, is if you have to use your own documentation months after you finished with the project, you'll know if you got it right!


    --
    ajt
Re: creating documentation
by sanPerl (Friar) on Dec 28, 2005 at 05:42 UTC
    I demand following things from my subordinates/team-members.
    1)Details of Design before they touch the code. Written in their words. This one should include names of proposed Modules and subroutines and their functions.
    2) Relationship diagram between modules.
    I was very much keen on all these things, but engineers working under me Don't always write Design report before coding due to pressure of schedules, I can always understand their problems and hence I have to create a script to provide a) Design report b) Relationship Diag of Modules c) Tree view. in order to satisfy company's policies.
    You can refer my Autodocumentation. I would be glad if it would be helpful to somebody.
Re: creating documentation
by davis (Vicar) on Dec 27, 2005 at 19:43 UTC

    I'm a programmer. I don't read documentation unless I absolutely have to. I'm trying to solve my problem not yours. I want examples which I can cut-n-paste into my code, and carry on with my day.

    This is my personal opinion, but I think that's what you asked for....

    davis
    Kids, you tried your hardest, and you failed miserably. The lesson is: Never try.
Re: creating documentation
by stonecolddevin (Parson) on Dec 28, 2005 at 00:53 UTC

    Fantastic feedback all! and that HOH stuff is pretty lethal...;-)

    My idea, like john_oshea mentioned, was to have someone else write it. I figured I could put it out there, at least in some sort of "beta" release, or have an online demo, get the documentation/bugs worked out for that, then release it as an install, and work to beat that best down. Does this sound reasonable?

    Also, another question is how to get a large and diverse enough audience to check through all of it, to test it, to try it out and get opinions from. I know perlmonks is a great spot, but what else?

    As for sobriety, yes, I feel that a lack of opium derivatives in my blood stream seems to help ;-)

    thanks again all!

    meh.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://519297]
Approved by marto
Front-paged by bart
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (6)
As of 2020-07-13 12:18 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?