Re: requirement documents?

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

The ability to use a simple editor or word-processor at a reasonable typing speed.
A reasonable standard of written english (or other project language).
A willingness to learn, a thick hide and persistence. A 'sunny disposition' can help provided they are not too bouncy on Monday mornings before say ... 5.00 pm:)

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

Comment on Re: requirement documents?

Replies are listed 'Best First'.
Re: Re: requirement documents? by demerphq (Chancellor) on May 13, 2003 at 16:35 UTC
I think you missed a close font tag. :-) Excellent post. I have been saying this (to no avail) in my present team/company for a long time. All those people who think making developers document their own code is a good plan are nuts. My experience is that developers usually have several orders greater understanding than the user/management does of the systems they are working on and computers in general (no suprise here). What is a trivial matter not worth even mentioning to a developer can be a point of crucial misunderstanding leading to a show stopper for a user. To expect a developer to even be able to lower their mind to the level where they cover what needs to be covered with the detail appropriate for an end user is a great way to ensure your documents are unusable. Sure there are developers out there who can do this, but they aren't common. This remind me of a story from my long distant past. I was doing some remedial mathematics and was having some problems with some stuff. So I went over to a see a good friend, who was at that time in the first or second year of his math PHD. He _tried_ to help me with my homework, but in the end we gave up. The reason was that he just couldnt forget his skills. One question was expected to result in around a page of sums, he stepped in and used some rule they dont teach you untile 2nd or 3rd year Math that reduced it to something like 2 lines. Of course this was no good to me. My point here is that expecting a developer to write documentation that is usable by a noncomputer expert is like asking my friend to forget all the math he had ever learned and to return to thinking along the same lines he did in high school. No chance. --- demerphq _{<Elian> And I do take a kind of perverse pleasure in having an OO assembly language...}	[reply] [d/l]
balance b/w coder, business and user documentation by g00n (Hermit) on May 13, 2003 at 22:24 UTC
Every software development project should have a writer. For a big, well funded project this person may have the title of 'technical author' ... Coder hate to document ... write stuff that is entirely unreadable by anyone without a CS/coding background and intimate knowledge of X, Y & Z. There is some truth to the comments here. But I will add, "who are the documents for?". Coders need specifications where everything spelled out in great detail. Be it formal specifications or an agile process you have to be able to express the result in binary. There is no room for interpretation. If you are on a large team and assigned Foo class you may well be interested where it fits in the class heirarchy - something a BA or non-cs/it writer cannot reasonably provide. Management types want to know what they are spending their money on and is this product alligned with my business objectives. It is here that a writer may be of some use, distilling the bar product into some language that makes business sense. Users dont read documents and only want documentation if all else fails. But end user documentation is worth it's weight in gold. Many a project has failed because users cant just read the source. Hence writers again prove useful in generating documentation. As a result I never really mandate any one documentation/specification process or set of hard rules. Each project is different. Instead I try to provide the right balance of documentation between coder, phb and user.	[reply]
Re: balance b/w coder, business and user documentation by BrowserUk (Patriarch) on May 14, 2003 at 01:40 UTC
Okay. We agree on the case for documents destined for Management types and Users:) You have a problem with the idea for (for want of a better term) 'technical documents'. I would still contend that having a 'third party' do the writing is not just beneficial, but essential. Though I do agree that the writer in this case may well need some technical expertise. The two best technical writers I have worked with both abhorred anything to do with programming, and the worst was a frustrated programmer! The problem with having coders write their own documentation, is that they approach the problem from a coders perspective. The result is, that you end up with documents that need a folding editor, replete with hypertext linking and a recursive descent "de-geeking" parser to read them. This is why so much technical documentation is so darn difficult to read and use. The skills, knowledge and mindset required for producing complete, concise, accurate distillations of large volumes of technical information, especially if this will ultimately be viewed in a flattened form (ie. paper), are considerably different to those involved in writing programs, and this should be recognised. A good technical writer does not have to understand the systems, processes, techniques or datastructures that they are documenting. Their skill is in extracting the salient information (with pliers if necessary:) and organising it into a logical, maintainable format. And being dedicated to that task regardless of the priorites and emergencies in the development process. Spelling it correctly, indexing it well, and making it look nice in terms of layout are nice-to-haves, but this is a secondary function that can also be done by a WP/DTP specialist who has absolutely no understanding of the content. My reasoning for removing the burden of documentation from the programmer is not that it is secondary to the code. Far from it. It is at least as important as the code. In the longer term especially. What my reasoning does say is that as it is so important, it should not be left to the coders to do because they will always consider it secondary. Recognising that producing documentation is a seperate, highly skilled and valuable part of the development process means that it should be recognised as a seperate function. The reasons for suggesting that (in small shops with tight budgets) a recent graduate might ideal for the post are They need to gain experience and command lower incomes as a result (they are cheaper). The very skills that the recent graduate has (or at least should have:), self organisation, the ability to perform research, sticking to a timetable etc. are the very skills most needed in organising documentation. The bonus (for them), is that they get an inside view of the development process and produce documentary evidence of their involvment. In most cases there are at least one or two of the documents produced that the graduate can be allowed to take away, as examples of their work, without risk. These can serve a prospective new employer as a strong indicator of their mindset and abilities way beyond their use of word processor. In just the same way, a medium-sized sample of a coders code can serve as a good indicator of their skill level, regardless of whether it is of the same type of code, or even in the same language as they would be required to write in their new position. 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	[reply]


laziness, impatience, and hubris
	PerlMonks