Keep documentation with the code, or in a central Wiki?

Question

My company does custom software for several companies. We have dozens of small software projects (and some larger ones), each with its own history, quirks and processes. We document this in an instance of MediaWiki), and that has worked wonderfully. Code documentation, on the other hand, is usually put with the code in source control. That is, through comments, diagram files, etc., and also a readme file that usually just describes how to set up the dev environment.

My problem is this: The wiki is much better than plain text files or word processor docs for higher level code and development documentation, but it bugs me that it's not in the source control system with the code. I couldn't easily bring the wiki with me on a plane, for instance.

So where and in what format should I keep code documentation?

Answer 1

I know one company which never puts comments in code. Everything is in the documentation. Not sure I'd recommend it, but they do ship software which is pretty robust.

Answer 2

Our unit tests are our documentation. That way it never gets out of sync with the actual code (without a test failing!)

But, it's kind of hard for a user to read that documentation. So, I guess it depends on who's reading your documentation, and how it's being used.

Answer 3

I agree that Wiki documentation has many advantages. Most places I have worked at that made an attempt to co-locate the documentation in source control end up not keeping those documents alive and you end up with stale information. With the Wiki format you usually find people keeping the documents alive, the way we all believe they should be, but seldom take the time to make sure of.

Increasingly I am finding it hard to think of a place where I can't get internet service to access my Wiki. I say Wiki-away!

Answer 4

What we do is: keep documentation with code, extract it during build and upload automatically to the web. This way it's editable in one place (code) and viewable in both places (code and web).

Answer 5

If you're talking about developer documentation, Tomo's response is pretty sharp. It's nice to have all the documentation in one place, but most users aren't going to care to have to sift through all the info. Most users will never look at your documentation, wiki or otherwise.

But in answer to your airplane question (pretty impressive that you'd be coding/documenting on a plane, I can't even pay attention to the in-flight movie on a plane), couldn't you run the mediawiki server offline?

Answer 6

I've found a real candidate: TiddlyWiki. The entire app and data are a single file. When it saves, it doesn't store history, only a modified date, which should be reasonably easy to merge conflicts on. Looks very promising.

Answer 7

The main question you need to ask yourself is this:

If I conceptually divided the information in my documentation to things that users should be able to find and read easily when they explicitly look for it, and things that they should become aware of when they aren't expecting them (e.g., some special requirements, protocols, etc.), where should I keep each type?

What you'll usually find is that the more removed from the code you are (e.g., using Wikis), reading it becomes easier (once you found it), searching for it can be easier or harder, but becoming aware of it becomes much harder. To illustrate with an analogy, a Bugzilla bug report is easier to read and to find (when you are looking for it) than a fixme comment hidden somewhere in the code, but the chances of someone reading the code becoming aware of the bug report compared to the comment are significantly lower.

Don't get me wrong, I'm a big fan of using Wikis in software documentation (and coorganize a workshop on wikis for SE), but they're not a silver bullet. You may very well need to use both mechanisms.

Answer 8

Umm.. your basic problem seems to be how to make the documentation in the wiki available offline.

It should be possible to export the wiki contents into an offline format.

Alternatively, store the wiki data directly into the repository! So, you can have your own server instance pulling out data from your locat copy. (You will have to make sure that the wiki data is protected from writes from general users; only the wiki server process should have write permission)

Answer 9

An option is ikiwiki, a full-featured wiki that can be managed both from the web and from a text editor. It contains tools to put it under version control (supports git, mercurial, svn and more) so you can have it alongside the code. I suggest you give it a look, it is a powerful concept.

Answer 10

On large systems I tend to have two sets of documentation:

• Documentation that is not likely to change in the future: Wiki. easily accessible.
• Code documentation: I use javadoc to document methods and this kind of stuff. This is likely to change as the code evolves and you need the documentation next to the code for keeping it up to date. Having this low level documentation in the wiki does not help, it just gets outdated.

So, then, in the build phase Hudson creates the javadocs for every project and uploads it to a public server. Then you have a link from the wiki to the javadoc. So, you end up having a nice introduction in the Wiki, which is easy to find and read, and gives you a proper introduction to the system, and then, if you really need to know more about the system you get into the code / javadoc.

Answer 11

I myself had the following questsions when I needed to document our product:

1. Who writes the documentation
2. Who maintains or styles the documentation
3. Are there several versions to maintain (Relase V1, V2, etc.)
4. How do I like to publish the dokumentation (printed, web, chm?)
5. What format should the information be stored in
6. Who will read the documentation?

For myself I answerd the questions like this. First my goal was to keep information and style separated.

(1) The develper documents the user-relevant changes in the raw docusource. (content)

(2) There is a technical editor that keeps the style in a good shape.

(3) We had several version released and need also to maintain those.

(4) We need printed (pdf) versions and would like to have an on line version.

(5) Plain text. The reason for that is, that if a wiki database format could not be read any more (server down, crashed, etc.) I do like to get the documentation content out of the system in a readable way.

(6) Mainly users. So I am talking about end user documentation NOT API documenation which is being generated automatically if the source documentation is present and vital.

This said I like the follwing combination most (at the moment). Keep the documentation in docbook format (Plain XML and readable by any xslt transform tool). Store this together with soure. That way the versioning flows like the source flows (-> no effort here). Community content (tips and tricks not yet in the documentation) could be stored in a wiki. My prefered wiki framework is Dokuwiki since it stored content as plain text and supports namespaces, that I like to use as version separator.