Ah, documentation. Whenever starting a project or picking one up, I love to read the docs. However, someone has to write and maintain those documents. Depending on who the audience is (and how big the company is), it may be a developer who is maintaining them. It can be a hassle, but I like to think of documentation, as a gift to “future me”. It will cost me now to create the docs, but it will be helpful in the future when I’m troubleshooting a project I haven’t touched for months.
At Culture Foundry, we use multiple repositories for our documentation. Because of the power of the URL, we can link between them. The location depends on the audience, how the documentation is generated and who is writing it. The primary locations:
- Google drive is our primary documentation repository because it is easy for anyone to create and access documentation. It can also hold PDFs or other less changing forms of documentation. However, Google drive search is not really that good, so make sure you pick a good naming system. Here at CF each client has an acronym and we put that acronym on pretty much every piece of documentation for that client in Google Drive.
- Lucid charts for our network diagrams. This is a URL addressable charting tool.
- Github readme files for developer setup and development specific documentation like best practices. Links between this and the Google drive documentation can be really useful.
- Trello cards can be sources of documentation and explanations why a system ended up in a certain way. However, it’s best to copy the relevant information from the Trello card to one of the above forms, because Trello cards are hard to scan quickly.
- Slack discussions. These have the same strengths and drawbacks as Trello, but are even less structured. I find these most helpful when they provide more context around a decision.
Here’s what we document (on the development side):
- System level documentation (here are the big pieces of system X, and here’s how they fit together)
- Requirements for systems we are building.
- Standard operating procedure (“this is how you do X”)
- Developer system setup
I have been a fan of documentation for all of my professional life. Documentation is never done, and a key piece of growing your documentation is for everyone on the team to feel like they have the time and power to update, expand, remove or change the documentation.