DEV Community

Cover image for When & How To Document New Technologies
Gregory Wolanski
Gregory Wolanski

Posted on • Updated on

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, 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 January 27, 2017 on Medium. Some rights reserved.

Discussion (1)

ikirker profile image
Ian Kirker

This is going to sound a little odd, but I recommend against MediaWiki as a documentation system, having used it as one.

The reasons why have a lot to do with the work people don't see that goes into making Wikipedia usable. It's easy to see that someone has to write Wikipedia articles, but it's equally easy to overlook the many, many hours of community labour that go into making Wikipedia articles look and feel right, link to other related Wikipedia articles, and ensure that orphaned pages are either linked or removed. If you don't put this sort of parallel effort into maintaining your documentation's hygiene and structure, things will get lost, things will get out of date, and your documentation will slowly rot as you add more pages. And that'll mean spending a significant amount of time in the MediaWiki editor, making templates and checking links, and looking over Special pages. It's just not worth it.

This will happen with other systems as well, but MediaWiki seems to encourage it more than others, and it's harder to fix. It does at least have good tools for finding old and unlinked content, unlike, say, Confluence.

For this reason, I think I'd recommend a system whereby you can easily pull out and look at all the content in one go, and operate on it with tools you're familiar with. This essentially means something that brings it out as files, whether it's a Jekyll-style static page generator, or a Gollum-style files+git-based wiki, or a single-page wiki.

For the record, I'm aware there is a contrib git-connector to MediaWiki, but I'm not sure how well it works -- I've only tried it in the hackiest way possible. Even so, and this is another point against it, MediaWiki's format is not widely used elsewhere, and I've not found another system which will expand its templates.