Random thoughts on process.

[Neil D Matthews <Neil Matthews sonydnse com>]

I guess that these should probably be in a GDP FAQ or whatever, but...

How do people see the process for generating documentation, etc? E.g. will it be based on the usual practice of frequent release / bug-report / recode (rewrite) / rerelease, etc.

What do you envisage as the process that each of these stages might take? and what file formats might these take?

Current practice in other places is to, e.g.

author publishes from source

interested parties use the documents produce "issues", cf buglist.

interested parties proofread the documents and rewrite sections to improve them, cf patches.

[iterate start]

author incorporates addresses issues and incoporates patches back into the source (using track changes)

republish with change bars.

interested parties review the modified versions of the text (within change bars), more bugs identified / patches, etc.

[iterate end]

So what's the best mechanism that people envisage being used here?
Is the gnome-doc-list an appropriate place to post comments on documents?

-------------

What tools make it easy to automate this process?

• Can we augment the DocBook DTD with extra "drafting" DTD's that allow changes to be tracked / comments to be added easily?
• Can this documentation process feed back ideas on extra functionality back into the wider Gnome effort? E.g. track changes / changebar support?

------------

Basically, what are acceptable mechanisms to provide comment? At the moment I'm using Acrobat to add issues / comments with .ps / PDF's --- what are the comparable Gnome sanctioned file formats? Is it just at the level of the docbook source? and context diffs?

Many thanks,

Neil Matthews.