Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?

Re: Writing Good Documentation

by maverick (Curate)
on Jun 24, 2002 at 19:20 UTC ( #176903=note: print w/replies, xml ) Need Help??

in reply to Writing Good Documentation

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*!!

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://176903]
[Corion]: perldigious: That seems to be more the export and likely it's the recipients of that export that like the titles changes
[Corion]: ... "changed"
[Corion]: I usually expect fixed header names, but am sometimes lenient in the order of columns. But changing the report titles often sounds to me as if you are not the sole consument of the export ;)
[shmem]: perldigious: as always - if it ain't broke, don't fix it. Ther must be a very compelling reason for changing column names in a database. Those are rare.
[Corion]: If you have whitespace in the column names in the database, whap the DBAs ;)

How do I use this? | Other CB clients
Other Users?
Others about the Monastery: (9)
As of 2017-05-25 13:35 GMT
Find Nodes?
    Voting Booth?