Home Home

The documentation is the spec

Arseni Mourzenko
Founder and lead developer, specializing in developer productivity and code quality
February 23, 2015

A problem encountered by most developers and teams is that any project requires to perform a lot of tasks in parallel. Writing code implies doing a bit of design, refactoring should be done at the same time, but there is also testing, and documentation, and requirements, and... well, you get the picture. Beginners can easily be depressed by the number of tasks to do, and end up with no testing or no documentation or no design.

Another depressing aspect is redundancy. We learn that duplication, would it be data duplication or code duplication, was invented by the devil and is an actual hell for DBAs and maintainers. At the same time, the business logic is duplicated between code, unit tests and acceptance tests, and documentation and requirements look pretty similar.

But isn't this similarity a sign that duplication could be avoided?

It looks like it could, and it is, and while the idea is not as popular as it should be, it actually produces positive results in many projects.

Take requirements and documentation, and more specifically the end-user documentation of an API.

  • Is there something which should be included in the documentation without being in the spec? Probably not: if you are documenting a behavior which is not described in SRS, your SRS is incomplete. For instance, a range of accepted input values, documented for a given API action, should also be in SRS.

  • Is there something which should be included in the requirements without being in the documentation? Yes, the relevant internals, such as every non-functional requirement of performance. But what if we take in consideration not only the end-user documentation, but also the internal one?

Working on Iris, the public documentation is actually the spec. I wrote the documentation prior to the development of the API, and update it on regular basis when implementation details indicate that the spec... sorry, the documentation is incomplete. I did a bad job of documenting every aspect of the API, but if I did, it would be a damn good spec by itself.

This also shows a flaw in many corporate projects. They start with a draft of the SRS (which usually takes a form of dozens or hundreds of pages of unreadable crap nobody uses because of disgust), then the project is implemented, and finally documentation is written. But why? What if we document the project before implementing it?

Iris showed an interesting (and common) pattern. I drafted a few things on paper before starting the project: not much, just two pages of diagrams and general concepts.

Then I wrote the documentation, and found that my prior drafting was not only incomplete, but also partially wrong. The term “incomplete” is key here. It means that the documentation actually helped thinking about the different aspects and details of the project.

Then, I started both the implementation of the project itself, and the client side, that is the part of a different project where the API is actually used and translated into pretty images, nice rounded buttons and other UI stuff. Surprisingly, it's not the implementation, but the usage which revealed a few other aspects I missed when drafting the documentation (that's why eating your own dog food is essential).

The essential difference, I think, is that documentation involves higher responsibility. When people write the spec, they have in mind that the spec will be read by only few people. Therefore, they won't take necessary efforts to think about it and to write it well, which in turn makes it too disgusting to be used by anyone. On the other hand, documentation requires care, and this sense of doing something important which really matters may encourage to think about the details and to write well.

This works perfectly for APIs. I haven't tested it for desktop applications, but I have an impression that it will work too. Have you? Was it successful?