Documentation guidelines

[Adam Hardy <Ad...@bbc.co.uk>]

Hi List,

I just completed a project and have to write a 'support' document, and
looking at other projects here, it seems to be up to the author of the
project as to what gets put in there. 

There is a 'tech spec', 'functional spec', a 'test spec' and various
other documents and the result at this point in time is that my project
has duplication of documentation in Word, Maven xdoc, javadoc and
READMEs! 

I would be grateful to know if there is a structure, framework, or set
of guiding principles behind the Maven-generated websites. I need
somewhere to find definitions of what there is to document, what the
audiences are and so on. Is there something from W3C for instance?

I typed in "software development documentation methodology" into Google
and got over a million results, which is a lot of chaff to wade through.

Ideally I'd love to be able to produce all my documentation in xdoc and
have a tool to produce output from that with whatever content and in
whatever format - even to the point where I can avoid duplicating my
javadoc overview. 

However right now it doesn't seem that there is even a good xdoc-based
editor in existence! What do people on this list use most?

Thanks
Adam

http://www.bbc.co.uk/

This e-mail (and any attachments) is confidential and may contain
personal views which are not the views of the BBC unless specifically
stated.
If you have received it in error, please delete it from your system. 
Do not use, copy or disclose the information in any way nor act in
reliance on it and notify the sender immediately. Please note that the
BBC monitors e-mails sent or received. 
Further communication will signify your consent to this.