[Klug-general] KLUG Project

[Karl Lattimer]

On Wed, 2008-03-12 at 14:19 +0000, J D Freeman wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> On Wed, Mar 12, 2008 at 09:43:03AM +0000, Karl Buckland wrote:
> > It's no good having the best application ever written if people can't  
> > find out how to actually use it.
> >
> > And yeah, I'd be glad to help and write docs, but it means bugging the  
> > developers...
> 
> Not necessarily, Properly written code should work very well as a
> reference work from which the doc writers an work, without need to bug
> the develeopers. More over, it allows for a level of sanity check. If
> the docs written by the tech writers matches what was intended by the
> devs, you know you got it sorted.

lol, that's a total crock of shit...

Sorry, but seriously "properly written code"... technical authors still
need to discuss with developers and architects how the software
functions, how it is expected to function etc... in order to write
useful documentation.

I've seen the results of such -non contact- documentation and its like
they're writing it for a completely different product.

Also, you're creating a barrier to entry by saying that the authors need
to know how its written, and understand the language/syntax and design
pattern properly.

Documentation should be written in three main stages

1, code documentation, each function/method gets documented to produce
generated documentation

2, software developers and technical authors piece together the use
cases with the functional documentation and identify UI/other
interaction methods and their relevant parts within the system.

3, Technical writers take the accumulated documentation and produce
narrative text using the notes concocted in 2... 

Repeat process 2/3 until the writer gets it right.

K,