On documentation

From the giant companies to the startups, if you have software development there is someone thinking about the documentation of it. Documentation of structures, of code interfaces, of feature behavior you name it. There are plenty of views around on the subject and here is one of my favorites:

Working software over comprehensive documentation

This one is from the Agile Manifesto and I have to say it never gets old. Unlike documentation! The pun is intended.

It is important to not be black and white and understand the sentence not as abandoning documentation, but about rethinking the use and scope of documents, their audience and their importance. It states that it does not matter what the documentation says, the behavior of the software is the only reality that counts. If the behavior is wrong, harmful or uninteresting, it does not matter if by documentation, by design, it was written like that. It is not adding value. And something that does not add value has to be changed just like the software that contains bugs. Just imagine, if a software is not compliant to specifications but is out there generating money and pleasing customers, is this software “wrongly” built? Is it about being right or wrong?

Software is not defined by its documentation

Writing documents that people sign-off to so we are “protected” later on in case there are delays and changes used to be common place and sometimes, larger companies that went through cultural transformation still hold on to that practice. Because there are always delays and changes, even when people agree on things, no matter how good people are in forecast and estimations, I just consider it an empty contract. Will the software change after it has being documented? It is (very) possible. Especially if we are talking about the world of web and mobile apps. It is just a matter of chance. Documentation will always get old. It will always need to get updates. Just like software. But should both evolve together? Should documentation exist to the lengths it becomes a problem on its own?

I do believe there are important documentation to be written, but no matter its type, even laws and regulations, it gets obsolete fast. And placing too much emphasis on documentation will bring artificial problems such as “If software and documentation are divergent, who is the one to keep or fix?” and it presents itself in several layers:

• User Manual: probably written after most of the software is coded and covers parts that are essential to the usage, some troubleshooting, but even that cannot be extensive. Who has the time to read that 300 pages documents that states exactly how to use the new app? If it is too long no one reads. If the app is so complex that it requires the 300 pages it is probably unfit for its market. Either way, documentation will not save the day here.
• API documentation: APIs have versions that sometimes are conflicting or not backwards compatible somehow. APIs should have a documentation that derives from the code, because that is what you are documenting: the software that is about to be delivered and how to use it. The code that you are exposing in its current state. I am talking here about the whole shebang: endpoints, contracts, payloads. If you do not do that you will end-up with pretty cryptic documentation that cannot covers logically all versions of the software and you might introduce a lot of human error in the different versions of docs.
• Specifications: for software I am mostly against this type of documentation , the (in)famous “spec” and I explain it right away: it is an old tale habit of having an analyst and a coder, with different skills, that did not use to talk. Documents were flowing through several layers of the organization so by the time the software needed to be built we needed to have that information somewhere, signed and agreed upon. People with writing skills were writing. People with coding skills were coding. And most important: companies had time to have all those things happening serially. It was also extremely expensive to change software so people were making sure they could think about everything before delivering the software. It was about “But it costs less to fix an error in the beginning”. But that beginning was not even software yet. It was a functional spec, which I would say has very little place at this day and age to be so thorough.

Communication instead of documentation

A documentation should be seen as a starting point to discussions. Serially writing and refining specs and then having developers to get their hands is just impractical. In the current software development era things change a lot and fast. So much that the time to produce specifications and software introduces a delay bigger than it is acceptable by most clients or markets. And the documentation in those cases, while mostly an intermediate step, become obsolete before it is useful. Developers and Product Owners should talk. Developers and testers should talk. Even more so if teams are geographically distributed. They should brainstorm, take pictures of their whiteboards or use online tools to share information like the free whiteboard and the more sophisticated cousin realtimeboard. What is important is to sync-up and then go finish their job. Questions will arise and no document is question-proof. People will already need help to integrate their code.

Using documentation to assign blame is unfair, useless but extremely common. Should documentation be more important than the actual discussion about the software purpose, how to implement things and what is required to test? Clearly not. Sure, document your acceptance criteria in your user stories if that is absolutely important. But what are you going to do with the unforeseen scenarios? No bug can be filed because there was nothing written about that specific case? Should your specification document just have a final page saying that all non-previously thought scenarios are invalid? Just using a little bit of common sense we can see how documentation can and should occupy a secondary place in software development.

Too much documentation is also a problem

Forget the scientific community and just consider Wikipedia. Too much information can bu such a burden, just like no information. They can confuse, which brings someone to inaction just like lack of knowledge. You have to filter through, build on previous knowledge to know what can then be reused as useful information and discard the massive rest. Now think about that software that keeps evolving with several releases in parallel.

Also software documentation is not what it used to be. It became rather scattered. It is the self-generated API plus the regulations created by a government agency plus some text file explaining the main features, aka, release notes. Other than that it also includes the StackOverflow entries and all sorts of forums through which people try to obtain information about other IT products. It is no longer centralized and owned by the producer of an app or API.

Documentation is not always useless, but it is never enough

Consider final documentation. User guides. Public API wiki. A how-to. Inspect not only software products but your oven user manual or the details on a Caribbean cruise. They get smaller and smaller every day. They contain the essential 3 steps to something or a cute workflow with drawings and no words, like IKEA assembly instructions. They are not thorough. They cannot be. People will always have questions; give them a FAQ. People will always get creative; give them a call-center number to talk to an actual human being. This work is never done, even if the final product is out there, making a huge impact and collecting millions of users.

So, I am not burning documentation down. But my thoughts on are the documentation needs to be just enough to keep people on track. A few assertions that give people the North. In the world of software development specifically I would suggest a critical acceptance criteria that gets communicated somewhere. A sequence diagram on the more intricate exchange of the system. A map of the process because no one is aware of how it actually works. And in the end, the nodes of the information, when put together, hold the full knowledge: the brains of all the people who work with you. Leverage on that knowledge making it become concrete. A piece of paper is not concrete. Those diagrams and maps will eventually get obsolete. Accept it. Make your people talk and share and grow the knowledge they have.

A tangible result is money in or out because of a certain feature. Clients happy. A goal achieved, whatever that goal was when the feature was designed. A tangible result is that success. Documentation has to be minimal so communication can be maximized. Specifically on the case of the software specs, you don’t want people discussing about what is or is not written on page 4. You want them to discuss and agree at some point about the validity of a feature and how should it be implemented to make things right.

Any time a documentation discussion arises, dig deeper into what does it actually means for your product. Whatever brought up the discussion, remember: what you need is to ship that working software.

You want working software out of the door.

And you might want to continue your read right here, when we explore the Agile Principle #7 in more detail.

#metrics #Agile #documentation #specification #specs