The Detail Department

  • Our Services
    • Strategy
    • Analysis
    • Implementation
    • Training
  • Applications
    • Salesforce
    • Confluence
    • WordPress
    • Other Apps
  • About Us
    • Jodie Miners
    • Projects
    • Privacy Policy
  • Blog

© The Detail Department Pty Ltd 2016

You are here: Home / confluence / We need to talk about Documentation

We need to talk about Documentation

18-Aug-2013 by Jodie Miners

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.

Share this:

  • Click to share on Twitter (Opens in new window)
  • Click to share on LinkedIn (Opens in new window)
  • More
  • Click to print (Opens in new window)

Filed Under: confluence, events

Jodie Miners

Jodie Miners is the Director of The Detail Department. She can help your business move from vision to reality with the right systems for your business.
Her eye for detail and her understanding of the ‘bigger picture’ will create and integrate seamless business systems. Read More about Jodie…

View My Blog Posts

Search this Website

Subscribe to Blog Posts

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Latest Posts

Advice for Salesforce Career Progression

So, you want to learn Salesforce?

Your Business Needs More Than Just a Website

Q and A: Apps for Service Delivery

Using Wufoo Forms with Salesforce

Integrations are The New Black

We need to talk about Documentation

Tools to help write help documents

Moving away from Command and Control

My ultimate guide to getting started with Gmail