Monday, 4 March 2013

On documentation and organisational knowledge

It's been a while since I've written up a work orientated blog post. At the moment two (relatively ;) exciting things are happening. One is the introduction of JIRA, Confluence and GreenHopper and the other is working on a series of projects to upgrade customers, getting them onto the latest version of our company's main product. I'm working along the lines of getting three categories of info in JIRA/confluence:

1.       Jira work items
2.       Confluence (upgrade) project wiki
3.       Confluence wiki page per customer

The first item should be quite straight forward and contains information needed for the life time of that work and a point in time record of the system (i.e. what was the state of play when the JIRA was raised/worked on?). For example, a story on a feature has the handover documentation for the original implementation attached as word files, so the current state of play now is easily accessible. I've also then created a subtask to update a linked version of this held in the wiki (the word document content as a wiki page, to do this I've used the standard "Import Word Document" function to upload the handover documents).

The upgrade project wiki holds the "project headlines" of the project, e.g. quick overview of the client and how they will benefit from the upgrade, and any analysis that comes up out of it. This is a record and audit trail of the project (at a higher level than any JIRAs above). This is a natural extension of the project headlines that we had been producing as Word documents moved into JIRAworld.

Finally under the main product project a single page exists per customer and then sub-pages under that per piece of functionality/project. This should document the live version of the customer's system as it is now. This is currently less than ideal, for example looking at one piece of functionality for a client. I've imported the handover documents as they were delivered by project to support, and as you might expect each project only details the work they have done - so you need to read and understand all three links to get the overall picture. Hopefully the upgrade projects will smooth over some of this and detail the whole functionality as upgraded. But this may also require a slight culture change with on-going projects and their PMs to encourage and guide their teams to update the documentation (and not just add their own bit as a new page). This is the new bit where we can add value to what we already do, with very little extra effort.

As you can see the three layers build up in order of longevity and should give oversight about what was done, by whom and when. Also being a wiki we can go back in time and have a look at the page histories to see what the state of play was at any time this can be useful for comparing what a project changed at a high level, by looking at the versions of the customer page before the started and after the work caused the page to be updated (if that makes sense?)

Oh, one more thing I am trying to work on is getting pages that contain guides to some customer specific logic to be aware of and also the projects that either didn't get signed off or aren't quite in the core product yet (added with a warning as reference).

Once pages are in Confluence they can be moved around, so putting them in there isn't wasted effort as and none of this pre-supposes wherever the company decides where our source of truth is, each Confluence page has "Export to Word" and "Export to PDF" options, so we can take versions and save them wherever our hearts desire ... a network drive, Zendesk, Sharepoint, MySpace, Yammer, Salesforce .... the list goes on (as do I ;). This is one of the reasons I’ve pushed on getting it all in Confluence now, I know that I can export updated documentation as required at the end of each upgrade project and that it will be in a similar format to what we have now (if that's required).

Further Reading

One thing that is important is having a common language used by all the company's employees. The next step would be to also build up a glossary within the same wiki framework. OpenBet's approach to knowledge management uses a third party plugin to extend the basic Confluence pages, read about on the Atlassian blog here and part two here

Further developing an onboarding process for a green field product

This is  part of a series  about my side project  Bashfully , which aims to give graduates and other new entrants to careers a seasoned prof...