When & How To Document New Technologies

“Document late and slow” — who suggests something like that?!

My name is Greg Wolanski, I have several hundred hours of experience in documenting new technologies, I can point to an NGO that is satisfied with the documentation I created, and I’ll be your tricksy guide to the boring issue of documentation. Fasten your seatbelt.

Document late and slow

Working software over comprehensive documentation.
 — Manifesto for Agile Software Development

Creating new technologies and documenting them are two completely different processes.

If you document a new technology during its creation, you will have to change the documentation many times, throw away large chunks of it and manage a sense of wasted time.

It’s worth it to create the real documentation only at the end of the project.

Documenting late means wasting fewer resources and a chance for a perspective from a distance. Distance in creating documentation of new technologies also has a tremendous value in the form of dramatically improved documentation quality.

When I worked at niepelnosprawnik.pl, after designing the project, I programmed everything I came up with. And then I had to document this software. The time between the creation of the technology, between the programming and documenting, let me look at my code through the eyes of a stranger. I couldn’t remember what I had programmed 6 months earlier. This whole documenting–late–thing allowed me to create much better documentation than if I had written it during the creation of the technology for Niepelnosprawnik.

Writing documentation late also led to some positive changes in Niepelnosprawnik. The time granted me distance. The distance allowed me to look at the project with fresh eyes. Looking at the project with fresh eyes allowed me to catch cases that made me think, “Why is it programmed this way? There is a simpler/clearer/… way to do that!”

Emphasis on the quality of the documentation, not on the speed of its creation, allowed me to more wisely handle uncomfortable situations that you will also encounter in your project. When documenting some parts of Niepelnosprawnik turned out to be hard and tedious, I could be honest with myself and, for example, with you now: If it’s hard to explain how a piece of code works or what it does, it’s not well–written code. In such situations, in the process of creating the documentation, I ended up reprogramming fragments of Niepelnosprawnik — so that it was easier for me to describe them.

If someone tells you that one day or — ahoy, the adventure! — one evening he or she will create professional documentation for a project that will have taken longer than, say, a week, answer that you will not hold her or his beer and that you appreciate the professional approach to the subject.

Take advantage of Wikipedia

Did you know that Wikipedia runs on a free piece of software? A piece of software that is ideal for documenting new technologies in non–governmental organisations.

MediaWiki, the software behind Wikipedia:

  • Is accessible for non–technical people.
  • Allows you (not just programmers, engineers, specialists) to edit the documentation.
  • Allows you to share the documentation with anyone inside or outside of an organisation.
  • Maximises the chances that the documentation of your project will be a living document.
  • Eliminates problems such as “I have the documentation on another computer” or “In my version of the file with the documentation, there is no such thing!”.

Last but not least, using MediaWiki will make the documentation of your project look like Wikipedia. However silly as it sounds, there is something magical about it. Something that builds confidence and facilitates writing. I tested at least a dozen tools for creating documentation of new technologies and only Wikipedia’s software gave me a sense of “this is it; I trust this tool; I feel that I can focus on the content (not the form) and that the words typed here will not be lost”.

I strongly recommend MediaWiki.

Use your wits in the selection of topics

You most likely don’t have contact with documentation of new technologies too often. I understand that perfectly, even envy it a little. The task of selecting topics to be included in the documentation can be paralysing. But we won’t let this stop us from creating ass–kicking documentation, right?

I have prepared for you a little cheat sheet. If you don’t know what should be included in the documentation of your new technology, just think about:

  • What should a new person or a company considering involvement in the development of your new technology know to make a preliminary decision in two minutes?
  • What terms or slang did you and your team use during your work on the technology, the software? It’s worthwhile to write down these phrases and label them with definitions. During the work on Niepelnosprawnik, we made, for example, a distinction between the “old” and the “new” Niepelnosprawnik, which would have been entirely unclear for someone from the outside.
  • What does a new technical person who wants to further develop your technology have to do to start changing it using their own tools?
  • What are the technical requirements of your technology?
  • In 99% of cases, there are some files or a database associated with the new technology. What’s the structure of the files? What can be found in every folder, database table or file?
  • What external tools (open source, commercial) are used in your technology?
  • What needs to be done to maintain your technology and when does it need to be done?
  • Who should be contacted for support in the project? Consider this question for both technical and non–technical issues.
  • What kind of imperfections in your technology are already known to you?
  • What’s the password to any and all accounts associated with the project?
  • How do you handle the 3 biggest tasks associated with your technology? In the documentation of Niepelnosprawnik, I described, among other things, how to edit the dictionary of the synonyms for the search engine, how to add a page to the website with content editable from the content management system, and how to add a new language to the existing language versions of the application.

You don’t need to document all of the things mentioned above; it’s just a list to help inspire you. I hope it will help you a little with this boring documentation thing.

This article was originally published on December 9, 2016 on the ngo.pl.