How to make documents evolve?

Question

Hi All:

We programmers write code and we write comments to code, but we rarely write documents. But IMO writing documents is important and time-saving since when you've written a good document, you don't need to reply to all the questions repeatedly. You can do more hack!

But when the code evolve and it's easy to evolve the comments simultaneously. But the documents get obsolete. We don't want to update the documents since it's boring(since some examples are quoted from code, but now it's obsolete). So how to make documents evolve? Any best practices? How can we avoid repeating ourselves in document-writing?

---

Someone may say we don't need documents since it's all there in code, just read the code. But I think documents should be in a high-level with some answers which should be replied for hundred times and some examples to ease greenhands.

Answer 1

I like using a wiki for this kind of information. Because it's a wiki, almost by definition people understand that it's a live document, and in my experience people do keep it updated, especially if there are links to the individual pages in the source code.

Answer 2

Only the documentation in the code is not enough. Other technical (architecture, design) and non-technical documents are necessary, too. They have to be maintained.

In my opinion, what is necessary is discipline. In order to enforce the discipline, ensure documentation review to check that, when a task is done, the documentation is also up to date, no matter whether the technical person likes it or not.

Another way to motivate them is to explain the effect of lack of documentation has on their own activities (when maintaining other's code or modules, using other's work, etc). Whey they feel it on their own, they will become more motivated to keep the docs updated.

Answer 3

There are variuous kinds of documents and out goal is ensure that they stay in step with the code. I design development processes to encourage the well-intentioned, if forgetful, developer to do it right. So whereever possible I want the documentation to be "naturally" in step with the code, developer updates code, they with little effort can update the docs - try to reduce the number of context switches. Also note that much of what I propose natually associates a version of the docs with a version of the code. Using a good SCM we can get back to any version of the docs.

So let's look at some documentation types.

First, the API docs. I am a library (or sub-component) author. I make some changes to the API, add new parameters, add new methods. If the documentation is extracted from comments in the code then as I'm visiting the signature of the methods, and the Class declaration I can see the documentation. MY OCD kicks in and I update the docs. Painless, doesn't add much time. The build process extracts the docs job done. See java's JavaDoc approach for an example, but I've been doing this long before Java came along, it's not a new technique.

Now what about the conceptual, structural docs. Again where possible I favour extarcting that from the code. So I treat "Master" classes, or main entry points as worthy of extra documenation. If necesseray I including an overview JavaDoc perhaps at the package level. Now clearly more discipline is requried to update those docs, but as the same technique is usde for capturing them the inertia of "don't want to launch the workd-processor" is overcome.

Tutorial information: how about using some of the tests as living examples. The code must update the test (you do Unit Test, right?) So, annotate some key tests with explanations. Now if the API has changes that test code must change, and while we are there we update the docs.

That leaves large scale documents such as the archiectural overview, deployment topologies etc. Well there we just need to be disciplined. We're mature architects, so we just do the job!

Answer 4

For many teams, high level architecture documents are definitely required, detailing:

• components (including why the component exists and why it contains particular functionality)
• interfaces between components
• design constraints (e.g. dependencies only go in one direction)

In my experience code level documentation such as sequence diagrams become out of date too quickly and rapidly become a nightmare to manage. Unfortunately this seems to be what most people think of when you ask them to update the documentation.

Answer 5

I'd say the key is to use the documents. If they are getting frequent use by those on your team, then when changes are made, the differences will be noticed and can be fixed incrementally. If the documents are used infrequently, they get updated infrequently, and the changes become more difficult.

---

Joel Spolsky has a great blog series that touches on this issue:

Painless Functional Specifications

Answer 6

We maintain requirements(in form of a list - much easier than bulk of text!) and top level design document, where basic architecture, layers etc. are described. Low level source documentation is auto-generated. Anything in between is gray zone where one must weigh the costs/benefit ratio of keeping it up to date (costs can be enormous as potential to create inconsistencies is huge).

Answer 7

I write protocol specifications, high to level architecture documents, comment my code, and even write user manuals. The documents evolve as the product evolves and customer feedback. For instance, if multiple customers call about the same issue and it is documented in the manual, we may query the customers to determine what is missing and then we would add or clarify the subsection where it is not clear. In cases where other developers are using our API or protocol, we may modify / clarify where confusion lies. At least in my case, evolution occurs when something needs to be added or clarified but it only occurs if the product or manual is interesting to someone. Otherwise, they don't take the time to provide good feedback.

Setting up a MediaWiki is a great resource as well. However, unless it is constantly updated, it is no better than a hyperlinked PDF. Wiki's offer an ability for your customers / users to add to the over document base as well. An internal wiki is good for documenting evolving specs and tracking history.

Answer 8

Evolve non-source-code system files just like source code. Refactor it to remove duplication. We version-control ours right along with the source code.

Refrain from just saying the same thing in multiple languages/formats. The only exception is if only one format needs to be actively maintained because the others can be generated. For example, a detailed class diagram that is automatically generated from source each night is OK, but a class diagram that has to be manually synced with source is not.

Answer 9

Literate programming tools allow the documentation and the source code be the same document. I'm not advocating LP - just pointing out one way in which project documentation can be more entwined with the project.

Answer 10

Documentation that people use and need is generally kept up-to-date (and tools such as wikis help in this).

If you have documentation which isn't used (e.g. as part of the development process to create acceptance tests) or needed (e.g. for legal reasons) then you're fighting a battle you can never win in keeping it up to date.

Answer 11

So how to make documents evolve? Any best practices? How can we avoid repeating ourselves in document-writing?

This process needs to be as smooth as possible or it won't happen.

If you need to check-out a document from a SCM, eventually lock it if it's not already locked (because it's using a damn binary format so you need to avoid conflicts), launch another tool than what you already have running on your desk, fight with the formating (because it doesn't support code highlighting), etc, there is 99% chances that documents will become obsolete after the first revision. And I've seen this happening enough to know it will.

That's why I love Wikis that much for documentation (even functional): wikis are collaborative, they are easy to update, everybody can do it, they have good support for code, you can link directly to parts of code with a good one, you can make diffs, you can assemble pages into bigger documents, etc, etc. And if you need to version the content for a release, export the content/database/whatever. I like wikis, I can't work without them.