Writing a project documentation – everyone’s or at least the programmer’s nightmare, right? Although at a first glance many of you will most likely agree with the given assumption, I’ll try to convince you otherwise. Not only it doesn’t have to be a dull experience, but it might be a truly fun and quite refreshing activity, which shall provide the great value for the project.





Before we begin, I’d like to mention that this article isn’t about providing details how to write a documentation using this corporate style guideline that results in hundreds of pages of text which describes each function and variable. Some software solutions have such requirement and I get that, there’s probably not much you can do about it. And well, if that’s the case, most likely there’s a separate team within your company that is responsible for doing so.

What I’d like to encourage you to do, is to think about documentation not only as a form of describing your project (so it can be quite a good read) but even a sort of advertisement.

And it also might be quite a powerful tool used for refactoring, just like tests.

It applies to both the open source projects and the paid solutions (as well as mix of these two), so I’m going to focus mostly on the scenario where you’re documenting your software e.g. using GitHub or any other online repository which supports the Markdown syntax.

Please note that I’m not going to directly use any of these two, as there are just tools and writing an interesting documentation is all about its form – they just happen to be quite popular ones.

Alright then, how do we start? Honestly, it really depends on how well do you know the project that you’ve been working on in general. You should have quite a good understanding of what your software does and what it was designed to do in the first place. Being one of the main contributors to such project means you should be good to go, however, if you’re a part of the bigger team and was focused on some particular component or domain, the first thing you ought to do is gathering the knowledge. Getting the good overview of the whole solution is the core requirement that has to be met in order to write a marvelous documentation.

Speaking of the knowledge in general – whether you’re about to write the docs, solve the calculus during classes or trying to convince somebody to your brilliant ideas, it all boils down to being able to explain the complex things in a simple way. Please, think for a while about the following remarks before you start the actual writing:

Do I really understand the project?

Am I able to describe what it does in a few words or sentences?

Is it possible to explain it using simple notions without specific, very technical concepts?

What would I say to a potential customer if I were to advertise my software?

Could’ve been some particular process/workflow/function/entity done better?

Now, stand in front of the mirror (or turn off your display if you have a glossy one) and talk it out loud to yourself (the abstract of your project).

Did you convince yourself? If so, that’s great, I think you’ve just found out what to write at the very beginning of your docs. Otherwise, keep trying until it sounds neat and most importantly easily understandable without possessing the specific domain knowledge (if possible).

Since I’m mostly focusing on the documentation written in a form of a “cheat sheet” (e.g. the popular one page README.md files being displayed as the first thing while opening the repository in your browser), the order of things is quite important here. Remember, the first impression is the most important one. If someone opens the docs and the first thing this guy will see is going to be some wall of text describing the very specifics concepts of the provided solution mixed with some source code etc. – well, unless this person is really into what you did, most likely he/she will go away or if you’re lucky this individual might start scrolling the page looking for something more meaningful, yet the frustration will be increasing with every second. Therefore what is visible right away is the key.

You have definitely much more elasticity when it comes to arranging the other sections.

Here are some of my suggestions:

Project logo + motto (if there’s one). Very informative, yet short description – sort of a project advertisement. Core features – what does it do in details. Quick start – how to build/run the software, minimal code examples etc. Resources – links to the detailed documentation, examples and so on. Extras – for example used technologies, how to customize the application or contribute to it.

I’d suggest sticking to the points 1,2,6 but feel free to modify the order of 3-5 as you want.

Of course, you can add as many other sections as you wish. The most important thing is to preserve the “flow” of the text, so it can be read as an interesting article.

If you try to implement here a sort of top-down strategy, you can really interest a reader.

I might be harsh here, but being able to write an attractive text is a sort of a talent or gift which doesn’t mean you can’t improve on it by writing more and more. Anyway, think about this one-page documentation as a “technical essay” and try to write it down this way.

I’ve said that documenting the software might be treated as a powerful tool for refactoring the code. Actually, it’s an implication of being able to describe the complex things in an easy way. Or making the complex simple (cheers to John Sonmez).

Once you start writing a detailed documentation (using wikipages, readthedocs, apiary or any other tool) you will quickly realize that sometimes you’re stuck, because of this uncertainty what and how should be written. And this is the perfect time when you should stop writing and actually start thinking if the code is good enough. Maybe I could add more properties to this class? Extract an interface? Use different design pattern? You should ask yourself these questions unless you’re certain about the answer that you did it the best way possible.

You need to have a common sense when to stop refactoring, though, just remember what the great Albert Einstein said: “everything should be made as simple as possible but not simpler”.

I do believe that you could probably write a book or documentation (I know, I’m a funny guy) on how to write a documentation, but it’s not the point of this article. What I wanted to convey is that whatever you do, whether you’re writing a code, tests or the mentioned documentation you should try to deliver the best that’s possible. Do not treat this as a necessary evil, especially when you’re trying to gather attention for your own project (e.g. the open source one).

This is one of the most important aspects that may be a deciding factor whether you succeed or not.

Write a text that you’d like to read by yourself. A text which is neither too short, nor too long, yet answers the most important questions about your software. Put some empathy into it, think about being a salesman and make a reader stay with you and enjoy what you did.

Here are some of the many projects with a nicely written one-page documentation:

And the ones that I’m working on (so you can see that I’m not just a pure theorist):