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.
- No location available
-

(highlight:: 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.)
- No location available
-

(highlight:: 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)
- No location available
-

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.
- No location available
-

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.
- No location available
-