good chemistry is complicated, and a little bit messy -LW |
|
PerlMonks |
comment on |
( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
Most of the question about what and why have been answered, but the outstanding question is who. Every software development project should have a writer. For a big, well funded project this person may have the title of 'technical author'. For smaller projects, including 2/3/4 person efforts, a school leaver (*) or a part timer is ideal. * I've been reliable informed that the term "new or fresh graduate" might be less humourous in US parlance. They only have to have three qualities
And one non-attribute: They mustn't be a coder of any form They must then be invested with sufficient authority (preferably from within the group, not above it) to be able to nag any and all individuals for information. Their job is to write down, and type up whatever information, documentation etc. is agreed as being required, and getting it done to the schedule that is agreed up front. And that means that they have the authority to sit beside the developer and ask questions whilst the compiler is compiling, the coffee is brewing, the Dilbert page loads, and whilst the developer is studying the insides of his eyelids in the hope of inspiration. Anyone who says that their project cannot afford such a person is wrong! Trade the time lost in having developers document -- ie. write macros for the word processor, spending hours getting the diagrams exactly right, and going into excrusiating detail of how the hidden scrolling atttributes pop-up works -- against the wages of a non-coder, and the math always favors having such a person. The benefits of having just one person who can tell you the state of play of each of the agreed documents, what (who!) the hold ups are, and chasing up approvals, if applicable, are incalculable. Coder hate to document, and when they are forced to, they will spend inordinate amounts of time 'fixing the broken WP/editor', producing better graphs, tables, diagrams, layouts, macros and whatever OR write stuff that is entirely unreadable by anyone without a CS/coding background and intimate knowledge of X, Y & Z. The writer, not being of this background, will need stuff explained in simply, clear terms and should be encouraged to write it down that way, in their own terms -- just right for Managers and Users alike:) Examine what is said, not who speaks.
"Efficiency is intelligent laziness." -David Dunham"When I'm working on a problem, I never think about beauty. I think only how to solve the problem. But when I have finished, if the solution is not beautiful, I know it is wrong." -Richard Buckminster Fuller In reply to Re: requirement documents?
by BrowserUk
|
|