Re: Documentation

["Simon 'corecode' Schubert" <corecode@xxxxxxxxxxxx>]

On 27.07.2005, at 16:28, Jan Grant 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*.

Never said something different.  I absolutely agree.

> 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.

I expect developers to cooperate with people writing docs.  But(!), as 
there are few people writing docs, developers need to document 
themselves until there are enough doc people so that all changes can be 
documented by those.

cheers
  simon

--
Serve - BSD     +++  RENT this banner advert  +++    ASCII Ribbon   /"\
Work - Mac      +++  space for low $$$ NOW!1  +++      Campaign     \ /
Party Enjoy Relax   |   http://dragonflybsd.org      Against  HTML   \
Dude 2c 2 the max   !   http://golden-apple.biz       Mail + News   / \

Attachment: PGP.sig
Description: This is a digitally signed message part