Perfect documentation

Mariusz Saramak
Mar 8, 2016 · 3 min read

I don’t like writing documentation for software project. Who likes ? The answer is obvious — nobody. But I write documentation because I have to.

I can fight with this or I can leave the job ( but this does not change my situation ) or I could try to minimize my pain.

My pain is that nobody read documentation because it is usually not up to date. Nobody wants to write documentation because nobody reads documentation because it is not up to date.

I don’t read documentation, I don’t believe documentation. Software is like new home electronic device — I play with it and I check documentation when something goes wrong. In our software case you do the same but usually documentation is not up to date and usually it lies.


Java doc says:

method return a list of map markers.

and under that we see:

List<MapElements> getElements()

Which is true? The code or the documentation ? I think the code. Because I believe that in 2016 everybody uses some advanced editors and this method could be changed when someone refactors the code.

Refactoring is an element of circle of TDD — We should not avoid refactoring, we write a tests,a unit test,an integration test and other tests to get assurance that our code after refactoring don’t brake anything. Do we have the same certainty that our documentation after refactoring is not brokes. That it doesn’t lie ?

Perfect documentation should be:

  • auto generated

Yes, you see correctly only one point.It should be auto-generate as much as it is possible to be good.

  • Who works on the project — I don’t want to provide this information by hand. I want to use git to check who works and pass this list automatically to the documentation:

git shortlog -sn

  • I don’t want to put to the documentation what dependencies should be imported to the project and which version and what licence is used under these detentions. I want to use the command bellow to list project dependencies with version numbers and put them to documentation.

./gradlew dependencies

Finally the documentation.

I don’t want to write documentation is HTML or HTML5 even. I want to use some markup language. Why ?:

  • I don’t want to thinking how my html will look like in Chrome, Firefox and IE. This should look like the same and tools which convert my markup language should take care about that.
  1. My markup language should be simple. The document should have mostly only the documentation, not a markup tags.

2. My documentation should be versioned. Markup language can be versioned in git branch.

3. My markup documentation could be auto generated.

4. Markup language should be able to convert to html, pdf and others

5. It must have possibility to write easily own extensions.

6. It must have possibility to include source code into documentation by start and end tags. This is the most important because even when we refactor code, tags stay and we are able to refactoring the code and still have valid documentation.

7. It should have possibility to define own templates. Example I get a request to generate confluence page with documentation then I should use my documentation based on markup language to confluence.

Sphinx vs asciidocs

  1. hatasciidocs markup is easier to understand and learn.
  2. both can be versioned in git
  3. I notice that both markup languages offer some possibility to provide variables. But could be better.
  4. Sphinx and asciidoc give possibility to convert to many formats.
  5. In sphinx the extensions are written in pyhon. In asciidoc we could use java

More From Medium

Also tagged Testing

Apr 6 · 4 min read


Top on Medium

Top on Medium

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade