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).
Comments
Post a Comment