Beyond Code

Indispensable Project Documents

Nevertheless, I find that there is a small list documents which are absolutely indispensable for a successfull project.

Indispensable Documents:

1. Mission statement

   A brief (one page) description what the project tries to achieve.

   Trying to get this on paper, in such a way that other people can actually figure out the project's scope and intentions from it, can be a very sobering experience. It forces a minimum degree of clear-headedness and realism early on.

   It is important that this document strictly obeys the One Page Principle: "A specification|design|procedure|test plan that will not fit on one page of 8.5-by-11 inch paper cannot be understood" (attributed to Mark Ardis via Jon Bentley).

2. Feature Document

   Also: Functional Requirements, Use Case Document

   A bulleted list of all the features/use cases the finished system is intended to support.

   I see two mistakes often being made with use case documents:

   • Usage scenarios which differ only on a minor point are treated as separate use cases, instead of as variations of some primary use case. Example: if a user can choose Fax or Email as notification methods for his account, the use case should be: "Choose notification method (Fax/Email)", instead of making this two separate use cases.
   • Overlong textual descriptions are given for each use case, leading to inane documentation. I don't think I have ever found a full-sentence textual description of a use case that has actually added value. Let's face it: most systems are not that innovative. "Sign up for account" as a use case description tells me everything I need to know (possibly augmented by an enumeration of the most important fields that need to be collected during sign up).

   If a system or only a part of it is truly complex, it helps to prepare use case documents on several levels of granularity: where necessary, complex use cases are broken down into variations and sub-use cases. But these details are kept out of the top level list, to avoid cluttering the bigger picture.

   The use case document may contain (tentative) priorization and assignment to specific releases.

3. Non-functional requirements

   Performance, reliability, fail-over behaviour, maintainability, operational questions, portability, extendability, ...

4. Both (functional and non-functional) requirement documents should also outline what will not be done!
5. List of screens or pages

   A simple list is sufficient, except for truly non-obious cases. Textual GUI descriptions tend to be quite useless.

6. GUI prototype

   The efficiacy of a GUI prototype as one of the most useful tools to explore the scope of the project and to solicit valuable end-user input is well known these days. Unfortunately, few projects realize the full power of good GUI prototyping.

   The prototype should not be considered a workproduct of the "technical" part of the project, but as part of requirements elicitation. By the time real code gets written, it is too late for GUI prototyping. Start early!

   Don't waste time making the prototype functional - static pages (and possible some navigation between the pages) is fully sufficient.

   It is very important that the prototype is built using a technology (such as HTML or VB) and environment (integrated GUI builder) that allows rapid prototyping, so that a variety of different approaches is really explored in reality. Difficulties to rapidly change and modify the prototype tend to lock the project quite quickly in to some most likely sub-optimal design.

7. Project Plan

   A best-guess schedule. Make the best possible effort in creating it and keep it up to date.

8. Release Plan

   Specifying the functionality (use cases) to be included for each separate release of the software.

9. Conventions

   Conventions to be used throughout the project.

   Not variable naming or code layout - we are past that, but architectural/behavioural conventions such as:

   • file naming conventions
   • class naming for repeated patterns in the app
   • which patterns to use for repeated problems in the app,
   • error exception, logging conventions

   The benefit of such conventions lies less in (anyway unquantifiable) improvements in maintainability, nor in forcing some level of uniformity on the development staff, but in freeing those developers up from having to make certain decisions from scratch over and over again!

10. Custom Tool Documentation

    If the project is using any sort of non-trivial build process, there should exist a one-page description thereof. Since tools built by the project team are usually not considered deliverables, there is no perceived need for additional documentation. Resist the temptation. The life you save may be your own (if your build master or tool smith is on vacation, quits, or is otherwise unavailable).

    The same goes for project specific unit and regression testing tools.

11. Annotated High Level Module Overview

    As annotated (!) graphic, to give an immediate overview over the principal parts of the entire system.

    Some textual description should be right there on the diagram - drawings alone are not able to convey all the necessary information.

12. Detailed Design Diagrams

    As appropriate: Technical or Business Domain bbject model diagrams, Entity/Relationship (ER) diagrams.

13. Deployment plan

    As appropriate: the distribution of the major technical components onto the available hardware (primarily for distributed and server applications)

14. Directions document (optional)

    Idea scratch-pad. An ongoing collection of ideas for additional features that might be interesting for a future release. Keep adding to it and review it occasionally (for instance, with each major release). Some of the best ideas end up forgotten in the struggle to finish the current feature, unless they are written down somewhere.

Purpose of Project Documentation

1. A hedge against staff turnover: both somebody leaving, as well as a new member joining the team.
2. Writing up a mission statement and a feature document forces a modicum of up front thinking early in the process. "If you can't write it down in English, you can't code it!" (Peter Halpern via Jon Bentley)
3. A feature document or use case list can serve as a check list, to make sure things don't get forgotten.
4. Having conventions frees developers from having to think about the same problems every single time again.

All of this is less important for research driven development or for-fun projects. The assumption here is a commercial, ie. schedule- and budget-constraint project.

Hints for effective project documentation:

• Avoid useless documentation. Make sure every document created addresses some real need and generates genuine value to the project.
• Focus on the unusal, don't belabour the obvious.
• There is no need to fill space: short documents are good!
• Bulleted lists are your (and your reader's) friends - don't use full-sentence descriptions unless you have something relevant to say.
• Make docs easy to prepare and maintain - if it is not easy, it won't get done. Or it will get done, but the documents won't be maintained and will whither away. (If there tends to be resistance to creating documentation in the first place, it is usually much worse when it comes to maintaining it. Make it as easy as you can!)
• Representative looking document templates emphasize presentation over content (marketing vs. fact). There may in cases be a genuine need to produce glossy and polished documents as part of the overall project, but they should not be mistaken for and kept separate from the actual project documentation. (Project documents are for the project, marketing documents are for the customer/client!)
• Don't be afraid to produce annotated documents (mixed docs) - eg Visio diagram with extensive notes on the diagram itself! A graphic without description might not be very informative, a text document describing a graphic is particularly dreadful and ineffective, keeping diagram and text in separate documents virtually guarantees that they will get out of synch.
• Don't forget that written documents don't have to be inane! Documents get actively sabotaged by disgruntled developers!