Documentation Patterns

Patterns:

SelfDocumentingCode and TheSourceCodeIsTheDesign are solutions. But solutions to which problems? The same problems that lead to DesignPatterns?

Problem:

With documentation, you face the same problems as with programming: You have to be able to change everything fast and cheap so you write everything once and only once. (DesignPatterns are just footnotes to the last sentence. This is why XP is about DesignPatterns).

This is what I want from the documentation of large projects (these projects may be larger than possible with XP projects):

Document everything once and only once
DontDocumentObviousThings?
Configuration management
Single entry full text search in each document
Document inheritance
Links that open new documents when I click on it
Links that include a document when I click on it
Links that include a document automatically
Different write protections for different roles
Given (and validated) structures for given types of documents (like Interfaces in java)

Such projects are often not much of a programming project (Implementation of an ERP like SAP R/3, JDEdwards...) so most of the documenting people usually use MSWord and don't have programming experience.

Do you confirm with these DocumentationPatterns? Are there tools that implement most of the needs? Which are good patterns that meet these needs?

-- GerdCastan?

While you are programming, always create TechnicalDocumentation? in parallel with your programming and unit testing. The TechnicalDocumentation? should be geared toward an audience of semi-technical support staff, and include parameters and tuning characteristics that will apply to your system.

Once you are in BetaTesting, use a TechnicalWriter to create UserDocumentation?. As your development staff will be up to its ears in fixing bugs during BetaTesting, having another person to create UserDocumentation? is essential.

Why wait so long to begin work on UserDocumentation?? Begin early by producing a "skeleton," outlining structure, content considerations and scope. In addition, both commercial and in-house UserDocumentation? frequently requires style considerations (template) such as headings, tabulation, look-and-feel for illustrations, captions and tables, header and footer, lists, etc. Make these decisions early. The skeleton is then filled out and "tweaked" as the software systems develop.

After your product has been in production for a year, and most major bugs have been squashed, take your time to have an Analyst, Trainer, or Programmer rewrite the UserDocumentation? to reflect the way the system really works.

AAAHH!! Run away! Run away! Documentation is either needed or not. As such, it should either be kept up to the nanosecond or relegated to the dustbin. Certain environments say the document -- be it requirements, specification, design, whatever -- gets changed long before any code gets created.

In medical and industrial instrumentation -- where safety is an issue and sometimes lives are at stake -- XP really doesn't fit the development environment. All this gibberish about how the code speaks for itself and you aren't going to need paper is just so much rubbish when the FDA or OSHA come knocking on your door. Does your environment or project require any kind of documents? Well, then documents first. Code later.

What happens if I lose some code? The doc tells me what it was supposed to do, so go do it again. Or somebody develops a whole new scheme for a different section of the project that won't interface to what I have now? Who has the right idea? Go back to the doc. Suppose I fiddle away two weeks trying to get my act together but I still can't figure out how to do this functionality? Ashcan the code and go back to the doc. How do I know that Sam, Joe, and I will independently develop functionality that will play together nicely? Documentation.

It is clearly false that documentation is either needed or not. It might not be needed today, but needed tomorrow. For example, if a development group is small and colocated then they don't need a lot of documentation, but when a bunch of maintenance programmers start, or when another group in a different city decides to clone the software, they will need more documentation. It might be needed for political purposes but will be ignored by everybody. That is why tools to generate flowcharts or UML diagrams from code are popular.

Documentation is useful in letting different groups independently develop functionality that will play together nicely. But the other points are red herrings. Documentation is more likely to be wrong than code, because it has no test cases.

DocumentsFirstCodeLater is a statement of faith. Justify it.

Hang on a second here -- you just proved my point. Small, colocated groups don't need documentation. Okay. Now, you add an outside group and you do need documentation. So, it wasn't needed yesterday but it is needed today? The need is now there, so the docs have got to be right.

Docs made for management who will never read them are not needed. "Political" reasons aside, they don't have to be particularly accurate, so any feeb can bang them together using a UML tool, comment extractor, whatever. These are not design documents. These are appeasement documents and can be treated as just so much pocket fluff. I know people who like to throw all kinds of wild-ass stuff into the reports they make for management just to see if the suits are reading this junk. The design docs that real developers use need to accurately reflect the plan.

Documentation is more likely to be wrong than code, because it has no test cases.

Some projects put most of the documentation into the user manual/tutorial. It lists the steps to get the job done. Most people remember the steps better when they know why they are doing them, so the tutorial has notes explaining why some things work, and other things don't.

Because the tutorial is a list of user stories, it has test cases. These test cases can be automated -- or they can be performed every day by the users of the software.

Unfortunately, just opening the documentation does not execute the test cases, so the documentation is still more likely to be wrong than an automated regression test suite.

This is making the ExtremePresumption? that an automated test suite actually exists and is used. On the other hand, in a more "real world" (that is, process-free) development environment, the code is written by a single person and has no automated tests. The developer tested it as best he could, and QA took his word for it that it works (this isn't hypothetical, I've been there). The design document, on the other hand, was written by the same person, but passed around to several other people, who actually read it and gave him some feedback (been there, too). In that case, the code is more likely to be wrong than the document is -- the document has had more scrutiny.

LineByLineReview is a ProtoPattern based on these ideas.

For many projects, the documentation is the UserStories. The documentation specifies what the project should be, regardless of how it was implemented. Documentation is necessary on these projects.

Heck, UserStories are documentation.