Civic tech product management: Documenting tech products
Good product documentation should be an inherent part of your product. Without it, users may have problems navigating your website. Lack of proper documentation can also bring problems inside your organization. In case you change or even expand the team of developers, the documentation will help new members onboard. Tech product documentation can be divided into two parts: user and technical documentation. Skip to the bottom for the Documentation Checklist.
User documentation
Designing for and with your users from the beginning should result in quite self-explanatory websites. Whether for communication purposes or for onboarding less internet-savvy users, it may be beneficial to create additional documentation focused on the usage of the website. Such documentation may take various forms, some of which are presented below.
User documentation can be an animated movie like the one from Funky Citizens’s Factual fact-checker or K-Monitor’s Red Flags.
User documentation can take the form of a guided tour around the website, as done with the popular IntroJS library, which highlights parts of the website together with popups with explanations.
User documentation may also be a screencast — recording of your screen with an audio narrative overlay. It’s relatively easy and cheap to do. First, prepare a scenario of the screencast (which feature you want to show, where you will click, etc.) and then execute it while recording your screen and explaining what you are doing into the microphone. Repeat till you are happy with the result and then post it online. You can use Open Broadcaster Software, the QuickTime Player preinstalled on Mac computers or one of the many other screencasting tools. At Fundacja ePaństwo, we’ve been using screencasts to present features of MojePanstwo opendata platform (we only have it available in Polish, but you will get the idea):
I find such documentation practices much more intuitive than an old-school written user documentation. There’s a reason why Youtube hosts around 61 million unboxing videos. 😉
Technical documentation
When your developers or contractors are gone, the technical documentation is crucial for the new team to understand how the product was constructed and how it operates. It will also help onboard new developers, especially if they are working remotely. Technical documentation should guide one having basic knowledge in target language and framework used in installing the product locally for development, as well as configuring and installing it on the production server. It should provide an overview of the project code architecture. If the project is planned to be adopted by other organizations, a clear adoption guide should be present: how to translate the interface, how to map your country data, how to extend the project with new features.
To make contributing to the project easier it’s good to include some sample data or sample data generators. It’s frustrating to have to set up the project and have to add users, their roles, categories, find photos in the right dimension, before changing, for example, only the styling of the title.
Last, but not least: do you know Alidade.tech. It’s an interactive guide for tech facilitators working with non-tech clients in order to find technology tools that suits their social change project. It makes you ask all the necessary questions. I’ve got quite inspired by it and started to create similar guides to the tools I am deploying. See ones for Moonsheep and Monitorizare Vot.
How to document tech products?
The general rule is to keep the documentation alongside the code. This way, all the crucial resources are gathered in one place. If changes to the code require changes to the documentation (and they often do) — it’s good to have both versioned in the same place. Below, I suggest how to practically document the product with some examples of Github integration.
As I’ve said, the general rule is to keep the documentation alongside the code. The common way is to create a subdirectory called doc or docs and put your documentation there. I recommend writing it using either Markdown language processed by MkDocs (simpler option) or reStructuredText language processed by Sphinx (more robust option). Both solutions can later be imported by Read the Docs project. K-Monitor’s Red Flags project sets a good example. The project uses Markdown language and MkDocs generator, keeps documentation in a subdirectory along project code and hosts styled version under project subdomain docs.redflags.eu.
If you have been writing the documentation in Google Docs you can convert it to Markdown using GDocs2Md script.
Apart from the main documentation, you should create a Readme file which briefly presents the project (see Red Flags example). If you are using Github, it will be presented on the main page of your repository.
You should also create a LICENSE file with the contents of your code’s license. On Github, you can choose a license from a long list of existing ones by creating a new file (using the button above file list) and naming it “LICENSE”. If you want to know more about how different licenses work or you’re not hosting code on Github (I recommend that you do), then head to ChooseALicense.com for more information on existing open source licenses. I recommend using aGPL v3 as the first choice.
Documentation checklist
☐ Readme file
☐ User documentation
☐ Technical documentation
☐ Installing locally for development
☐ Configuring and installing on production
☐ Code architecture overview
☐ How to extend?
☐ How to translate?
☐ License file
☐ Sample data (generators)
☐ Needs assessment surveys
Originally published at transparencee.org.
