how to organize documentation

Question

We are maintaining a legacy application written by Delphi, and there are lots of complex function in it.

So far we collect parts of the document(of cause, the part we coding..), and other are missing(or not even been written..) we build a big word XX.doc file, and its structure is like this:

1 function A

1.1 description

1.2 work flow

1.3 E-R model

2 function B

...

after did that,this file is so big that I don't even want to look at it again not to mention update it. does any one know how to make the document easy to access（Accessibility） or maintain?

What I really means is if there are some documentation management method or tools we can use to easily write,version control,change to html,pdf.... Not based on a particular program language.

Answer 1

Have a look at LaTeX. It is very well suited to maintaining large documents. You can split them up in seperate documents, which are put together when the output docuemtn is generated, with auto creation of TOC, index list etc. LaTeX can produce pdf files with hyperlinks, which makes the navigation in the resulting file much easier.

Another approach would be to write very simple html pages for each function, and compile them into an HTMLHelp project, resulting in a .chm file.

If you want to redistribute the results to customers, I would recommend pdf files - IMO it looks more professional, and it is platform independend. From a functionality point of view both offer the same basics (optional TOC tree on the side panel, text search etc).

The downside for both approaches is the learning curve: You need to invest some time to set up a system and train the users. But since you are dealing with fellow developers, neither HTML nor LaTeX syntax should be a big problem for them.

Answer 2

have a look at doxygen. You can write documentation in your header files and then generate real docs in pdf, latex, html and may nother formats. You can also use templates to customize results

Answer 3

We use docbook heavily for our customer projects as well as for open source ones. Briefly, docbook is an XML dialect that is dedicated for technical documentation. It can easily be transformed into various formats (PDF, HTML, OpenOffice). As styling is entirely pushed into XSLT there is a clean sepearation between content and presentation. A lot of the large open source projects (Spring, Hibernate) use docbook to create its documentation so you can easily get a quickstart impression from using the templates in the version control systems.