What really constitutes a helpful set of documents for software development? That is possibly a poor choice of words as there is not even a need to restrict ourselves to formal ‘paper’ documents for communication.
Have you ever heard:
- "You cannot trust the documentation because it is out of date."
- "I’ll need to ask a developer to look at the source code and get back to you on the definition for that business rule."
Statements that probably indicate dysfunctional documentation, but not without cause, there are a number of challenges:
- As a project iterates to maturity, things change. Keeping an up to date, extensive set of documents directly reduces a team’s ability to deliver software.
- Putting little or no effort into documentation creates a long term problem for the people who would like to know key information.
- What documentation is valuable?
- How should documentation be captured?
- How do you find a piece of documentation?
Looking at those challenges we can probably state the communication vision:
We can find key information.
So what is key information?
Key information is whatever anyone needs to do their work. Quite a broad scope, and probably the point of most disagreement in various documentation strategy discussions. How do we agree on a balancing point for the documentation content? It is too expensive to capture everything that anyone might ever need. So, how much will be captured so that it does not unduly hinder what we are doing now…or next year?
A helpful question to ask is: Who is the audience and what is their likely need?
OK, what tactics can be employed to capture key information?
- Construct a team culture that requires a number of people to know it.
- Video – a demo, someone talking about it, …
- Record (audio) someone talking about it.
- Photograph it (works well for those whiteboards that don’t print).
- Write it down.
Fine, we have our key information and it is valuable, how do I find it?
- I already know it.
- I know where it is.
- I can ask someone who knows the answer.
- I can ask someone who knows where the answer is.
- We have conventions on where to store information artifacts and I can browse them manually.
- We employ technology to search for it (eg a search engine like google).
An example:
A software system is developed and maintained.
Identified audiences and their needs:
- Software developers: high level overview, business requirements/priorities, system architecture, domain model/processes, business rules, source code, key design decisions
- Business owners: high level overview, domain model/processes, business rules
- Software users: training, system help
Communication Strategy:
To facilitate communication an intranet site is created which includes automatically produced documents (eg automated test output, automatic code documentation), a wiki is setup to store virtual artifacts, a forum is setup for the system users to ask questions and provide general feedback. A search engine indexes the whole lot, so the team can find information.
- High level overview: video the business owners presenting their hopes for the system, write a vision for the project (possibly already part of a business case document)
- Business requirements/priorities: record simple statements of key requirements, obtain regular access to key business people, provide constant feedback to key business people, provide an issue tracking system that captures issues and comments
- System architecture: produce architectural diagrams with technical and business viewpoints
- Domain Model/Process: produce domain model and process diagram(s)
- Business Rules: write up business rules
- Source Code: write source code with comments that may be extracted to a documentation system (for example javadocs).
- Key Design Decisions: write Technical Memos focusing on the decision
- Training/System help: none required because the system is so intuitive 😉
Note the focus is on valuable communication, rather than extensive documentation.
by 