Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"

Re: How to write documentation?

by Hutta (Scribe)
on Oct 18, 2001 at 20:36 UTC ( #119729=note: print w/replies, xml ) Need Help??

in reply to How to write documentation?

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...

Replies are listed 'Best First'.
Re: Re: How to write documentation?
by Anonymous Monk on May 23, 2004 at 10:22 UTC
    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?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://119729]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (4)
As of 2021-11-30 10:22 GMT
Find Nodes?
    Voting Booth?

    No recent polls found