How do you manage your external documentation?

Question

Depending on the project, there are a number of artifacts that might be produced. On top of the number of documents, they also come in many formats (and some are produced in multiple formats). So how do you keep everything organized and up-to-date, especially in a project with a large amount of documentation?

Answer 1

A wiki could be useful. Any items that are not normal documents (visio diagrams, UML, etc), could be attached to a wiki page that describes the document.

Answer 2

Well, we have several systems. We run a Wiki internally where developers can write text, create tables, add images (UML diagrams, workflow diagrams, etc.), files for download, and whatever else comes to their mind (videos if they want). The Wiki can be viewed with any browser (and every system has such a beast nowadays) and it can easily be edited anytime on the fly with an easy syntax (easier than HTML formatting IMHO). This is for internal documentation, from developers for developers.

For internal/external API documentation we have a database (that covers function calls and parameters as well as objects, their inheritance and methods, etc.). You can create it by hand or have it automatically created by a tool like doxygen from in-code comments. This database offers a function to export everything to LaTex, using a standardized layout, and LaTex can then easily be converted to either PostScript, PDF or even HTML.

For more advanced external documentation (not just describing functions and objects, including images and so on) we write it simply down using tools like OpenOffice.

Answer 3

Recently we have moved some of our documentation into a public-facing Sharepoint solution and made that available for the customer. Each customer can only "see" their projects and the related docs. Since Sharepoint handles the versioning and the allowed file types, we don't have to deal with those issues. The issue handling (only issues as we don't make any bugs) is also part of this CustomerWeb. The idea is that the process will become visible and enhance the collaboration with the customer. So far it is still a beta but we have high expectation :-)

Answer 4

Our documentation written in latex (we are in process of moving to docbook) committed into the source repository together with the source code, tagged and branched together with the source code. We produce 2 output html and pdf. Most of our documentation is API references but general description exist as well.
To summarize: we treat our documentation as additional source code that should be maintained exactly as a C[put here your language] source code, no differences, the code process review of latex source a little bit simpler but exist as well.
And i forgot to mention that we have 2 tech writers for about 30 developers that doing all this stuff :)

Answer 5

For one of our projects, we checked our end-user documentation into the code repository. The specs went into our requirements database (Quality Center). Other documents were on SharePoint.

Answer 6

On one project we used a Wiki for documenting during development, and then continued to update the Wiki after the project was rolled out. It worked out really well since end users could refer to the Wiki and add business processes as needed.