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.