From: Tansley, Robert <robert.tansley@hp...> - 2004-11-29 14:45:22
Definitely a good idea to break up the docs somewhat -- the main reason
they're monolithic at the moment is to make them easy to print out, but
plenty of systems out there let you have the best of both worlds.
> Worth considering whether an existing solution might do the job. Looks
> to me like Forrest (http://forrest.apache.org) has all the=20
> features you
Perhaps we can decide on an authoring system, and then a way to
integrate that into the UI separately, rather than conflating the two
aspects? E.g. DocBook for authoring, then something like Forrest for
More aspects to consider: Making internationalisation and localisation
as easy as possible. The platform should have 'generic' user
documentation, though many organisations might want to add in stuff
about local policies, guidelines, available help and so forth, so as
with the code they might want to customise.
Another issue is the system docs -- is CVS the right place for them?
When people submit patches should we require them to also patch the docs
appropriately? We could use the Wiki for system docs but the problem
there is it's hard to take a snapshot that corresponds to a particular
release. Perhaps the same solution for the user docs would work for
these. Or does anyone know what the SourceForge 'DocManager' does?
Robert Tansley / Digital Media Systems Programme / HP Labs