Documentation

[Jan Grant]

On Wed, 27 Jul 2005, Simon 'corecode' Schubert wrote:

> Jeroen Ruigrok/asmodai wrote:
> > > Never said that.  But who should keep the docs updated if programmers
> > > commit here and there?  It's pretty hard to follow changes then.  The
> > > programmer has the knowledge on what he changed.
> > Technical writers.  They are the ones that will harass the programmer with
> > relevant questions.
> 
> Iff they exist.

You need the right way to express this: which is, if a person wants to 
contribute, they ought to do so in the manner they feel best suits them. 
_Good_ documentation shouldn't be viewed as a less valuable contribution 
than good code*. If people have the skill to approach the journalistic 
task - that is, to ask the right questions of developers (and to lower 
the doc burden on developers), then I'd hope most developers would be 
willing to be approached, perhaps to run an eye over any resulting docs 
looking for inaccuracies. Both parties just have to approach the task in 
an open-minded fashion, with hopefully their shared goal (an improved 
system) in mind.

jan

* I'm not trying to be all my-little-pony about this: decent docs aid in 
comprehension of a complex system and can cut the time needed for even 
ace programmers to get up to speed. But only if they tell the truth.

-- 
jan grant, ILRT, University of Bristol. http://www.ilrt.bris.ac.uk/
Tel +44 (0)117 9287088 or 3317661   http://ioctl.org/jan/
Spreadsheet through network. Oh yeah.