Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change

balance b/w coder, business and user documentation

by g00n (Hermit)
on May 13, 2003 at 22:24 UTC ( #257921=note: print w/replies, xml ) Need Help??

in reply to Re: requirement documents?
in thread requirement documents?

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.
  • Comment on balance b/w coder, business and user documentation

Replies are listed 'Best First'.
Re: balance b/w coder, business and user documentation
by BrowserUk (Pope) 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

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://257921]
[choroba]: Good morning!
[Discipulus]: good morning choroba! the eu-crew is complete! ;=)
mxb waves

How do I use this? | Other CB clients
Other Users?
Others rifling through the Monastery: (8)
As of 2018-05-21 08:03 GMT
Find Nodes?
    Voting Booth?