How Documentation Tools Have Failed Development Teams

The vast majority of software development teams are dissatisfied with their development process. I believe 50% of the problems are traceable to bad documentation management tools. This blog discusses the state of documentation management tools for software projects, and suggests some concepts for improvement.

95% of software projects manage documentation with Microsoft Word, augmented sometimes by SharePoint. Here's what's wrong with this system:

1. It's too slow.
2. It's too hard to find what's changed, who changed it and when.
3. It's too hard to compare the current version to previous versions.
4. It's too hard to isolate parts of the documentation as hard requirements, so they're distinct from the background information.
5. The granularity is too big, so it's impossible to version control individual requirements.
6. It's difficult to work with individual topics, sections or branches.
7. It's difficult to email someone a piece, or several pieces of the documentation.
8. It's difficult to log on and quickly know what's changed since you last logged on.
9. It's difficult to know what you've reviewed and what you haven't.
10. As you code against requirements, it's difficult to check off what's done and what's not done.
11. You can't check in code against a requirement.
12. It takes too long to create a new, small document to, say, expand on a user story.
13. Multiple people working on a single document is a nightmare, if and when it works at all.
14. The concept of an element of a document, such as a requirement, user story, use case, implementation detail, etc. as an entity with a lifecycle and with a workflow unto itself, and outside the workflow of the document in which it resides, is non-existent and impossible to create.
15. ...

OK, that's more than a dozen, and it took about 5 minutes to think of them. I'm sure I'll think of another dozen before I'm through with this blog.

Now imagine if we wrote code the way we write documentation. Just write all your code in five or six huge documents and put it on a big SharePoint site. Do I have to elaborate on the problems? No I don't. It's crystal clear that working with code that way would be completely ludicrous and unworkable. It would lead to nightmares, breakdowns, and endless analysis of what's wrong with the process. It would spawn endless waves of gurus whose job would be to come in and tell us how tools are secondary and the problem isn't with the tools anyway, the problem is with the process. We need to communicate better. We need to meet more often. Or maybe the gurus would tell us that we need to have more formal methods for code sign-off, because clearly you can't be changing code after it's written without a change order.

Sounds familiar?

Ya, that's what we've been told about documentation for years.

Well, I say that's a pile of BS, and I say it's time people who write documentation management tools started waking up and supplying us with tools that actually work.

Now I don't profess to have all the answers, but here are some things that come immediately to mind for what a documentation management tool for software projects should be able to do:

1. Allow users to edit in a way that's like Microsoft Word, and create documents that look similar to Microsoft Word. Don't make users learn a whole new way to write. That's why people keep coming back to Word, because developers of documentation tools keep violating this most basic principle.
2. As the user writes, keep track of what's being written on topic by topic, paragraph by paragraph basis, and version control at these levels.
3. Enable a user to create a new document in less than three seconds.
4. Make it as easy to create many small documents as it is to create a few large ones.
5. Make project documentation a nested tree, where all the small documents can be centrally found as part of the larger tree.
6. Make it trivial for users to create new pages and start typing new documentation. Getting to where the user can type a new thought should take about 2 seconds. No more.
7. Enable the documentation to be rearranged easily on a topic by topic and paragraph by paragraph basis. Let me move paragraphs up, down, indent etc.
8. Allow a user to see a list of all changes since he last logged on, made by all other writers, in a single, central list. If the user clicks on a item in the list, he's immediately taken to the place in the documentation tool where the change was made, and the paragraph where the change was made is shown next to the previous version of the paragraph, with the changed text highlighted.
9. As the user reviews changes, keep track of what's reviewed and what' s not. Each user should be able to know instantly what changes have been made by others that he has not reviewed. Anyone who made any changes should be able to know instantly who has reviewed those changes and who has not.
10. Allow the document paragraph styles to be changed quickly and easily from normal to bulleted to numbered, to heading 1 and heading 2, with fast keystrokes, like Alt-L, Alt-N, etc. as well as having a simple row of buttons for doing the same thing. Don't create any more styles than are absolutely necessary. Don't make the user think about how to apply styles. Don't make the user wonder how to do indented list numbering.
11. Have a master documentation tree that contains all the documentation for the project. Have instant search on that tree. You type a letter or phrase and instantly the tree compresses to reflect the search, the way Outlook finally works, after years of crude, slow and nearly useless email searching in earlier Outlook versions.
12. Be able to attach document nodes to many types of project artifacts, and have the system intelligently realize what type of document node is being attached, and place the node in the main tree. For instance, a BA creates a User Story. Great. Now the BA wants to break the story down into a bit more detail, like maybe a use case, some more detailed requirements, and perhaps an implementation suggestion. The BA just clicks below the User Story and a new documentation window appears, ready to create topics on the left and enter details on the right. A template might appear as well. The BA bangs in some details and saves. Later on in the master documentation tree, under the "User Stories" section, that documentation node and its details appear. But as well, the implementation details the BA entered appear in the "Implementation" section of the master documentation. And the use case the BA entered appears in the "Use Cases" section.
13. Allow any paragraph to be marked as a hard and fast requirement. Just click a button or a key shortcut and the font changes, an icon appears next to it, and now it's clear that this thing must get done.
14. Now all hard and fast requirements should be able to be easily viewed as a list.
15. When a developer works on a requirement and completes it, allow the code to be checked in against that requirement. Alternatively allow that requirement to be expanded upon, like the User Story was expanded earlier. Just click the requirement and write some tasks, implementation details, etc. Now the developer can check in code against the individual tasks.
16. Show instantly which requirements are implemented and which are not.
17. Be able to show a version history of any paragraph.
18. Be able to show any prior version of the entire documentation. i.e. let's see what the documentation looked like a month ago. Ya there it is. There were 112 requirements. Now there are 134. Let's see where those are: click, click, click. Let's see who wrote those. Ya that was the client, that was a developer, that was the BA. Let's see what changes there have been in the last month. OK click, click, click. That's too many. Let's just see the changes to requirements. OK. Click, click. It's all instant.
19. Be able to export any section of documentation as a template.
20. Have documentation attached to the project, and be backed up and restored with it, just like source code is. If the user switches projects, he switches documentation as well.
21. Over time, start to build documentation static analysis tools that inspect the documentation for obvious flaws and suggest better approaches.
22. Over time, start to build workflow capabilities that recognize the importance of documentation elements (paragraphs) as entities with their own lifecycles.

Most of these things can be done with source code today. I find it completely unacceptable that we can't do the same with documentation.

This is something that's been on my mind for a long time. In recent years at my company, we've been experimenting a lot with the concept of documentation tracked at the paragraph level where each paragraph is a WorkItem in Team Foundation Server. By leveraging the ability to version control and link work items in TFS, we can get a lot of the substrate functionality much more easily than if we had to develop from scratch. As well, we can link documentation to other work items in TFS, making possible scenarios such the user story example I alluded to above. We're hoping to have a proof of concept available for download by the end of October, and will welcome feedback, beta users and contributors to the project.

And if it gets developed and works, there will be a free version.