Practical Documentation for Teams of Information workers

“Everyone loves documentation” – said no one, ever.

This article shows you how to make the bare minimum documentation work effectively for information workers.
Using a simple system, you will know what needs to be documented to get stuff done.

There are 6 things a document needs to tell you:

1. What is it? - what the hell is this process about (context)
2. Where is it? - where does this documentation live (link)
3. Who knows about this process? - so I can get some help (contact)
4. Why are we doing it? - am I getting paid if I do this task (customer)
5. When do we do it? - annually, on demand, when the boss says? (timing)
6. How do we do it? - ok, tell me the steps of the task I need to do (steps)
            

1. What is it?

Quick summary of what it is – doesn’t have to be a nice business case (though feel free to put a link to that), but clearly say what this is about.

Documentation should be for the team and named as the process that they do - eg "load Sales forecast", "refresh products database"

It is fine to name things your team understands - this keeps it simple and local, but helps to link to other teams processes as well.

2. Where is it?

Where you keep the documentation doesn’t really matter in the long term (more below), but the most important thing is to have a link to that documentation. This can include
- wiki page
- NAS drive
- internal website or sharepoint
- embed documentation with the process (python code, SQL comments, refresh scripts)
- cloud applications (Trello, Basecamp, Slack, Evernote)

3. Who knows about this process?

Who in the team started or last did this process (not so we can pass the buck onto someone else, but so we can get help / clarification if needed.

This could also be the customer (internal or external) that wants the job done, so they will know what is the expected outcome.

4. Why are we doing it?

Most times this is obvious (the customer or boss needs the task done), but it is worth reviewing the tasks after a year to make sure it is still required.

The why that gets documented here can simply be "Customer [frank] needs Easter catalog updated on the website each Febuary"

5. When do we do the task

If this is an adhoc task, you simply write "when we get an email to "[do the task]" and then your task is triggered by email.

For regular tasks, you just need the Month / day and how often it occurs, eg
- Full Backups = 1st of each Month
- Sales forecast = every Wednesday
- Pay processing = every 2nd Thursday

How do we do it?

This is the meat of the documentation - steps needed to do it can be a simple one line

load the import.csv file from T:\blah into the table TABLE_RAW in SALES_PROD
            

or it can be a 40+ step process going across multiple teams.


In a nutshell - document as little as possible (don't make it a big chore, or no one will do it), but enough to get the task done.

Managing your documentation

When do we update the documentation

- whenever a decision is made / changed (eg Filter on years after 2015, remove Products of type "blah" from forecasts)
- when a project is cancelled / finished, *don't* delete it (in case decision gets reverted), leave the documents in the same folders, but change the wiki page index so it isn't cluttered. Even if you need to add _DELETED in the title so everyone can ignore it.
- do not reorganize documentation folders, it breaks links and no one will update them (sharepoint is particularly bad for this - a complex link gives no easy indication of what folder it came from)

Backup

Make sure it is backed up - this is particularly important if you use a cloud solution, it is always a good idea to do an export of your data regularly

Example Documents

The following examples show how a short simple note on various tasks can help your team find and do tasks.
These seem simple and obvious, and it may seem like a waste of time but you will get new team members and many more tasks come along so without an effective system you can get caught out.

Document example - Cloud Backups

This shows the very short document needed to show team members how to do the extracts. It is important so everyone keeps the backups in the same place.

1. What is it? - Take monthly backups of Trello tasks
2. Where is it? - N:\docs\tasks\admin\backups.txt
3. Who knows about this process? - Jane set this up and usually does the task
4. Why are we doing it? - to keep local backup of task documentation in case of cloud issues
5. When do we do it? - 1st day of each month
6. How do we do it? 
    a) logon to team trello account as your team account ( https://trello.com )
    b) follow export instructions at - https://help.trello.com/article/747-exporting-data-from-trello-1
    c) save the downloaded ZIP file as trello_export_YYYY_MM_DD.zip to N:\docs\tasks\archive
            

Document example - Tax Returns

Example shown for small business in Australia required to do annual tax returns

1. What is it? - Tax return
2. Where is it? - N:\docs\tasks\finance\tax_return.txt
3. Who knows about this process? - Cassie
4. Why are we doing it? - required by law to submit annual tax returns
5. When do we do it? - 1st July each year
6. How do we do it? 
    a) get all accounting updated in the finance system
    b) run tax report ( Main menu > blah > magic tax report generator )
    c) logon to ATO with company id [see boss for details]
    d) fill out return and submit
    e) save confirmation to N:\docs\finance\tax_YYYY_MM_DD.pdf
    f) email Jane, Cassie with details
            

Next Steps

[ ] make a place for your documents
[ ] identify key things you wanted documented and make a short effective document for each one
[ ] make an index linking your documents
[ ] email the team, asking them to bookmark the index

Doing this means that everyone has the link to the same document and from there you can manage who does the updates, etc.