Where to put system documentation?

Question

Where would you put documentation for a team web project?

Our system is based on ASP.NET/C#, but I guess this problem is applicable to many other solutions/languages.

Currently, we have the following types of documentation:

• Text, descriptions, guides etc (mostly text, but some .doc)
• Visio files (graphs, flowcharts, database diagrams)
• Images (misc representation of data)
• Source code documentation

Text is pretty easy to handle, we have a Wiki for that. Visio files are put in a Documentation SVN repository, along with images and Word documents and the like.

Code is in another SVN repository.

The problem I have with this setup is this:

• Binary files are stored in a text-based revision system
• Code and documentation are separate, which means they easily gets out of sync
• It's a big mess, because documentation is scattered across the system

How do you keep documentation and code in sync and updated?

Answer 1

Don't worry about putting binary files in Subversion. It's designed to take them, although it's better at handling text.

Code and documentation will get out of sync no matter what, unless you enforce policies to keep them changed together. This isn't something that will be affected by having the code and docs together or separated.

If the documentation is in a few specified and known places, spreading it out won't be an inherent problem, but it would be good to have it all readily accessible. Can you link to the Visio diagrams etc. from your wiki, and have the images in the wiki?

Answer 2

The glib answer: Wherever it is most likely to get read, because it probably won't be anyway.

Better: keep your documents in subversion and don't forget to keep them updated regularly.

Even better still: store your documentation in the source code (as in, in the same files even) and auto-generate your documentation directly from your build process. There are many documentation-in-code markup languages available, like Doxygen which is excellent.

Answer 3

We do keep all documentation in the same repository as our source code and use the following directory structure.

 /code
 /doc
   /architecture # infrastructure decisions, plans, …
   /manuals # user focused documentation
   /marketing # marketing material, market research, …
   /requirements # requirements/issue tracking, backlog, roadmap, …
     /sprints # one file per scrum sprint

The doc hierarchy is inspired by the Wikipedia article on Software Documentation. The 'technical documentation' directory is missing because we put it in our source files where it belongs (javadoc, python docstrings, …).

Docs, PDFs and similar formats or even images should be fine. We do prefer markdown files for text (with extensions like codehilite and wikilinks) if possible. Here is why:

• they are handled by most diff tools out of the box
• they are quite readable as plain text (think email, text editor, machine parseable)
• they can be used as source for other formats like html or pdf

We actually use them to build wiki style web based documentation automatically.

Some source code hosting platforms like github and bitbucket also will display markdown and similar text formatting languages (textile, rst, …) as html.

This has several benefits regarding infrastructure and productivity

• if you check out the project you get both the source and documentation
• all documentation is versioned using your favourite SCM
• less context switching (use your favourite IDE with autocompletion, search, …) for code and docs
• your source code backup strategy now also cares about your documentation