Last week, myself and Kelsey van Haaster presented a talk at the Agile Business Analysts Meetup in Melbourne. The Agile BA’s meetup is my favourite Melbourne meetup group (it ranks second only to the Sydney Business Technology User Group that I used to help run in Sydney).
The talk was in two parts – Kelsey talking about Requirements documentation and me talking about Help documentation. The theme of our talk was using Confluence as a tool to help make documentation more a part of the agile software development process, rather than an afterthought or a tedious chore.
Having all the documentation in one place that everyone in the team is responsible to update, is, in my opinion, the only way to do documentation.
As part of the talk, we created a Confluence site to show some examples, and so you can see how we created the examples. We created a fictitious app called Time on Task, a simple corporate time tracking app, to show some example requirements and help documentation.
Kelsey’s requirements Confluence space is not yet public, but check back in a few days, and it should be. My help documentation Confluence space is public. You can click edit on each page to see how each page has been constructed, or add any comments if there is any feedback you want to give
In preparing these help examples, I also created a page listing out some examples of good help systems (and some not so good).
There is also a page showing what I think the anatomy of a help page should include. This example is for documenting a screen. For the ideal help system, each and every screen should be documented. All the fields on the screen should be documented, and the exact text of the field name should be on the page detailing out the screen. This allows users to search on any screen name or any field name in the Confluence search to find help about that field or screen. I have also included some tips on how to structure your Confluence help system.
On each screen page, also show the user how they get to this screen on the app. (Eg From the Home Page click on Settings, then click on My Settings). That way, if they find the help page by searching or linking from another page, they will know how to get there in the app.
As well as documenting each screen, also add pages describing the processes that the users need to follow and link back to the screens to use to do each step. An overall process page is a great idea, especially if the each process links directly to the page describing that process. FAQ pages and pages for each type of User are also helpful, and can link back to the help pages for the processes or the screens.
So, I would love to hear you feedback on what makes a good help system in the comments on this post or on any of the pages in Confluence.
