I’ve been thinking a little about documentation recently. In some ways, documentation is like the parable of the blind men and the elephant. Where the elephant is the concept being described and the blind men are the artifacts being produced. Each of the documents captures a facet of the whole, but not the whole thing. Every piece is an incomplete view of the whole item but taken together they describe a much larger concept.
That’s kind of the traditional approach, many separate documents each written from their own viewpoint. Hopefully, they all describe the same whole, when they don’t we have big problems, that happen all too frequently. What if it didn’t have to be that way?
What if you could write documentation by creating the whole, the elephant, and then having different filters to present the specific views, the blind men? Would this change things for the better? How could this work?
One way that I see something like this working would be to use kind a tagged wiki kind of approach. The advantage of this is that in the current era, wikis are pretty well understood. Using Wikis to Document UI Specifications provides a good example of using wikis for a specific facet of the documentation problem. But how would you provide more comprehensive documentation?
Creating the wiki pages, you could add tags for which of the facets the information applies, then generate the specific documentation periodically. For example, the mock up screenshot embedded in the wiki page would get tagged as being part of the UI guide, help file, specifications and statement of work. When we replace the Balsamiq mockup of the screen with a real screenshot, all of the different artifacts would get updated automatically.
Basically, you’d start the page with the user story. As I user, I want to solve this problem. As you start fleshing out the solution to the user’s pain the page gets more complex, gets split into multiple pages, etc. Maybe developers add their notes about the implementation details that only matter to them and QA. As the feature evolves, it gets updated, which cascade to all the artifacts.
Like everything in the world, there are new challenges that come up with every change. One of those challenging areas is communicating the changes, so that they can get worked on by the appropriate people. Probably the simplest way would be for the changes to get highlighted for a project manager to figure out if something needs to be worked. Although there is potential for the right automation.
Scott's Thoughts 