People tend to treat documentation the same way they treat insurance. It's something they know they should have. They understand the benefits of having it, and regret not having it when shit hits the fan but still don’t do it.
Something i've written about before
Article No Longer Available
So for context, I am currently the team lead for a team of analysts who service requests from within the business for reporting.
When I took over my team in April this year we had next to no documentation. My own induction, only a few months prior in September, was a handful of power point slides. I learned every other part of my job through a combination of asking my colleagues and figuring it out myself.
This resulted in an highly inefficient team, each staff doing the job their own way based on only what they could remember. It wasn’t so much a team as it was four seperate people doing the same kind of task.
Now it's not entirely fair to pin any blame on those who came before me, I've yet to see a workplace that understands and makes time for documentation. And the team I landed in was always rushed off their feet with too much work, even if they wanted to document things the company wouldn't give them the time.
While the team lacked documentation this was compensated by the experience held by the current analysts who had been doing the job for many years and so the team didn't quite suffer as much as one would believe.
However that equation changed very quickly. We lost one of the experienced staff members early into 2019 leaving the team with only 3 staff and we were set to loose the next at the end of May.
Basically as soon as I took over the team, I was going to loose the buffer of experience those two experiences staff provided to offset the lack of documentation. On top of that I also needed to hire and train two new staff.
So seeming I couldn't magically acquire several years of experience before they started I had to do something. So instead of becoming a silo of knowledge myself I set out to build a comprehensive set of documentation.
Of note is the fact that I had spent a few years as an Information Management Advisor. This meant a good idea of where to start and how to get there. But I wanted to share how I did this as the secrets to good documentation are not locked away in a Temple guarded by Librarians.
Step One: Map out what needs to be documented and make a plan.
Nailing how you will store and access your documentation from the start will make the all the difference. If it was as easy and just writing documentation everyone would have done it and the world would be drowning in a plethora of ‘final-Final_1.docx’
Before you start, you need understand the following key rules of information management:
- Information must be stored in a location anyone in your company can easily access: Your C drive or emails are not an easy to access place, my rule of thumb is; can my CEO access this whenever they want?
- Information must be naturally discoverable. Can someone, not using a search engine, organically find their way to this document. Basically is it stored where most people would logically expect to find it?
- Information must be self-describing. Either it’s name and or the surrounding eviroment must provide the reader with a quick understanding of what the document contains. For example you don't need to name something 'Blah Process Documentation' if its in a folder or section called 'Process Documentation' just call it blah. However still use descriptive naming.
- The above three rules must adheare to the KISS principle. Complex documentation structures fail overtime and get in the way of points one and two. Don't overcook it and get used to a few ugly scenarios where 'this document doesn't fit into any bucket' will happen, get comforatable with that, its all about the bigger picture.
With those rules in mind your next step is to build a document map. To start list off every piece of document you may need.
Once you have your list start grouping them into high level buckets, no more than six. A bucket should reflect WHY a staff member would go to that bucket not the theme of the subject matter.
By the end you should have at least two buckets. One being 'how to do the job' the other being 'non job specific documentation' for example if you are a developer, a process outlining how to submit code to the UAT enviroment would be in the former bucket whilst documentation about how to apply for sick leave would be in the latter bucket.
For my team we ended up with four buckets, they were:
- Team Specific Process information, aka how to do the job
- Supporting documentation i.e our team awards nomination page.
- Subject Matter information, in depth information on the companies subject matter that will aide in the doing of the job.
- Technical Information, i.e how to upload files into S3 and copy over to our redshift enviroment. Also this became a bit of a catch all.
The next thing to consider is where you will store your information.
It can be tempting to store everything in one place, which if you can, thats what you should do, but its not often that straight forward.
My team needs to store sql scripts, ticket information, our internal information, and information for our customers. How this shook down was that our code was stored in google drive, a folder for each ticket. Everything else about the ticket was stored in the ticketing software. Our internal information is on our companies intranet and the stuff our customers need to read is stored in a help centre everyone uses.
In a previous role we stored our processes on our intranet but our subject matter information was stored inside our ticket software as that helped us with tickets and our call centre had access to it too.
The split however should be logical, or be widely known as to what goes where. You can’t have inconsistencies.
So at this point you should have a document map outlining how your going to structure your information and where it’s going to go.
Step Two: Prioritise what needs doing
Now you know how your going to store your information you need to do it, but often the sheer amount that is needed is daunting. Like any project I recommend prioritizing it. So go back to your document map and sort it into the following:
- Needed yesterday
- Needed Soon
- Needed within the next 6 months
- Or later. This should help with deciding in what order you go about doing it.
For me and my team this was an easy task, because I knew i was onboarding two staff in June I aimed to gettting all documentation needed to induct them into the job done and put everything else on a 'later list'.
Article No Longer Available
Step Three: Make it an interative process
The biggest key to our sucess was approaching documentation as an iterative process.
I started off by making empty intranet pages with a set template and marking the pages that where incomplete, then over the course of weeks we slowly added to each page as needed. Some of these pages stayed in a barebones state until well after my new staff started and some of them where able to contribute to those pages as they learned things.
Step Four: Embed into culture and workflow
The key to how we got to 50k words as a team of four in such a short amount of time was due to how we made it part of our workflow and culture.
At the start of every ticket they will go search through our documentation to see what we have written on that subject matter and at the end of every ticket we go an add anything we learned in doing the ticket to our documentation. We also link that documentation back to specific tickets that would be useful to review later. I also gave staff time away from doing tickets to get some key documentation accross the line, for example one key table in our database has over 50 type codes and so I tasked one of the team in figuring out all 50 codes.
By bookmarking both ends of the process with documentation checks the team can instantly see the value in documenting what they know. We also haven't covered every area so when we get a ticket for an undocumented area the team really feel that pain in contrast of so many other things being documented, this then drives that desire to leave no rock undocumented.
Step Five: Make Time
By far the hardest step but having documentation saves you time at a later date. I found time to get documentation written while code ran or in between projects. Sometimes I outright lied to customers and stretched delivery dates so i hate time to get some documentation done.
Conclusion
Getting the documentation set up was hard but not overly difficult and now that we have been through the worst of it its paying its dividends. New staff have come onboard quicker than those before them, existing staff and others from around the business have thanked us for writing down the stuff that just existed in peoples heads. We were able to debunk a few inconsistencies now that we had everything written down and the team writes down what they learn as second nature.
Having everything written down has opened doors that were not open before. We’ve started building templated code based off the documentation that gets the most views. Able to refine existing processes an automate some key administrative tasks all because they were no longer living inside peoples heads. I also feel confident in taking leave away from my team as every process we have is written down and should they need a decision made based on experience they can lean on someone from our wider team.
Just like Insurance, documentation is worth it.
Who am I?
Ronsoak 🏳️🌈🇳🇿@ronsoak
Who am I? 🌈. Senior Data Analyst for Xero. Blogger dev.to/ronsoak - medium.com/@ronsoak . I draw sometimes instagram.com/ronsoak_art/ and I write Sci-Fi that no-one has seen yet. My tweets do not represent my company. 💬 Be Good and Be Good At it !00:30 AM - 02 Jun 2019
Top comments (1)
Nice tips to try, its really hard to motivate people to documentation a thing. But yes we need to prioritize it.