I don’t want this to be portrayed as a review of the book, because it is unfair to review a book seventeen years after its publish date. Our industry has changed, as has agile, and the problems we face today are based on a backlash against documentation that wasn’t valuable. Due to that, this book doesn’t have the value today that it did in 2003, but that isn’t an indictment of the book. Rather, the problems the author faced have been fixed in many cases. For example, there are 24 pages on layout and typography. The tools we use for documentation have largely solved that for us.

However, many small and medium sized shops are still struggling with documentation, and there are some key insights that the book addresses that we can take away.

Documentation Portfolio

Although he proposes the term, I suggest that this may need another name, as this term is also used in education for documenting the development and improvement of student learning, which makes searching difficult. However, this concept was the most interesting idea that I hadn’t encountered before. In the age of wiki documentation (something suggested by this book), we run into the problem that we create documentation ad-hoc. That is, we find something we need to document and tie it to the project page, and we rely on search or institutional memory to find it later. Certainly, ops departments are further along than on the development side, and that is because there are established patterns of runbooks, support knowledge bases, and operations manuals. Unfortunately, the design documentation patterns in early software development turned out to have a low value to effort ratio. However, it leads to the key point of the first section: projects should determine what documentation belongs in its documentation portfolio, and the documentation should focus on long-term relevance. Rüping argues that each project should define its documentation requirements individually, broken down by

  • The documentation required by project stakeholders
  • The documentation required for the team to communicate
  • The documentation individual team members might need to think things through
  • The documentation the project will need at a later stage
  • The documentation any follow-up projects will probably need.

He argues that the documentation, and its organization, should be re-evaluated on request. This follows from the unstated agile principle to prefer local control at the team level over departmental or company control of standards. While I think there may be value there, I also think there is some room for overall consistency as many projects or product teams can start from a baseline and evaluate for their project, taking established departmental patterns into account. As such, I think there is value in building a default set of document artifacts and patterns to consider, but can be adjusted as makes sense.

The book does not have a real set of documentation patterns at the “what are the types of documentation” level, contrary to what the subtitle of the book would imply. (The book is subtitled “A Pattern Guide to Producing Lightweight Documents fro Software Projects.” The organization of the book follows a Problem/Forces/Solution/Discussion pattern similar to the Coplien Form, and is written to be used as a pattern language.) However, it does give some categories of documentation alongside examples of the type of documentation:

  • Management documents define the management context for a project, such as the overall scope and project schedule.
    • Management Summary
    • Delivery plan
    • Project manual / team guidelines
  • Specification documents clarify exactly what software is needed and serve as a basis for discussions with the customer.
    • System overview
    • Use cases
    • Data model
    • Functional specification
    • User interface specification
    • Timed behavior (Note: I’ve never seen this before.)
    • Non-functional requirements
    • Glossary
  • Design documents explain how the software works and are used for communication within the development team.
    • Architecture overview
    • Data model
    • Class hierarchy
    • Class interaction diagrams
    • User interface design / event management
    • Database access / transactions
    • Integration with neighboring systems
    • Guidelines and naming conventions
  • Migration concepts may be needed if transitioning from an older system.
    • Functionality migration
    • Data migration
  • Test documents a a complete set of test cases and can make specification documents redundant.
    • Use cases
    • Test cases
    • Test concept
  • Usage documents describe how a system, module, or class can be used.
    • Usage guidelines / concepts
    • Cookbook
    • Tutorial
  • Operations documents describe how a system is to be operated.
    • Deployment
    • Operations guidelines
    • Troubleshooting

The author then says that these are well known from software engineering in general. While I appreciate that not everyone needs to reinvent the wheel, I think there would have been higher value in devoting an entire section to where and how to use these. The frustrating piece of how our tools interact today is that these are captured in systems that don’t communicate in a way that tells a coherent story and are hard to cross-reference, but that’s for another blog.

The Big Picture

The author has a great pattern talking about having a “big picture” document that I found valuable. Too often, we get mired in the details when looking at documentation, but the first thing we need as someone new on a project is an understanding of the big picture. That often falls to face to face interaction, and while there is value in face to face interaction, this will not help when someone needs to modify the project in five years. That interaction would be better served as a set of questions after getting an asynchronous introduction. Further, many of the technical debt issues we face in older code bases are trying to reconcile current usage with original intent, often called software archaelology. The big picture is the key detail missing from many of these efforts, as these are either lost in institutional knowledge or are filtered through later efforts, and these filters can make understanding original intent difficult.

Organizing project documentation.

While the author has much to say about the rule of 7 - that you should limit your number of sections and sub-sections to 7 +/- 2 in order to enhance understanding and to have sequential yet well structured text, I think these are both obvious and vague. Instead, I am drawn to something from an experience report. Too often, our documentation is a wall of text. Instead, we can have a short summary, a diagram, and details with enumeration broken up by whitespace. While I cannot link (as I don’t think this is quite fair use), I think DVC has a good example from end user documentation in their agenda section. It has a simple summary, a diagram that explains the steps concisely, and the rest of the usage document is well spaced and easy to read. This is a great example of what many of our onboarding documents could look like. (I have never used DVC, but I admire its documentation from first glance.)

However, I have seen many examples of entirely unstructured wikis. If we can think through a portfolio and align our wikis to read more as full fledged documents than semi-organized snippets, I think we can improve the efficacy of our documentation with only a small bit of effort. What, then, do we do with all of those pieces of valuable information that defy organization? I think there is value in separating that out into a “junk drawer” of the project so that the valuable portions of the wiki can be more pronounced.

Conclusion

I wouldn’t recommend this book to most people in 2020 unless they are in a deep dive of trying to reform documentation. However, I have yet to find the right book as a guide, and there is value at looking through older efforts to think through this difficult problem. I think that there were some valuable takeaways, and its list of documentation types is still relevant in determining how we should define our documentation portfolio through the phases of the project.