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.

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 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.

IntroJs self-demo. You can invoke it by clicking “demo” - http://introjs.com/

IntroJs self-demo. You can invoke it by clicking “demo” – http://introjs.com/

IntroJS in effect on Code for Poland’s Politikon.org.pl website. You can invoke it by clicking “Jak Grać” in the top menu.

IntroJS in effect on Code for Poland’s Politikon.org.pl website. You can invoke it by clicking “Jak Grać” in the top menu.

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 ePanstwo, 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.

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.

license-chooser

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)