loading...
Cover image for Yet another documentation dispute

Yet another documentation dispute

mdabek profile image Marek Dabek ・3 min read

Introduction

I have seen multiple articles encouraging developers to quit documenting while creating a software. I believe this is the direct influence of the Agile Manifesto and a quite a misunderstanding (in case you haven't noticed it says comprehensive not any in there).

I tend to disagree that we can completely drop any form of documenting our work leaving the code to speak for itself. One exception I would accept, is really simple script, application or a webpage. In other cases we are going straight off the cliff.

Why, why, why?

Software development is a form of engineering and it turns out that in other industries engineers tend to produce quite an amount of documentation.

First of all, an engineer is only a part of a delivery chain. It is really rare that an engineer (or team of engineers) provides a final product. That said, ideas need to be somehow communicated, assumptions must be made and limitations must be discovered. What is the better way to think about them and share our discoveries than writing them down? For Pete's sake, we are solving a problem here and someone needs to understand and agree to our solution!

If you plan to maintain the project till the end of its life, then you probably need to revise your plans. What is more, there will be times, when you will expand your team and lack of documentation will cause spending more and more time explaining how your system works to new team members. Documenting your work may seem irrelevant and waste of time in the early phase, but a high level overview, and some guidelines, and tips&tricks will save tons of work later.

One last thing, there is an industry wide metric called the bus factor. It defines how many employees need to be hit by a bus to lost crucial part of knowledge. Do you really want to be left alone with a pile of code which you are not familiar with, having no idea where to start digging, while your customers demand fixing issues? All of that because no one cared to draw few diagrams?!

How much?

There is a corporate knowledge, the more paper the cleaner your ... or maybe we stop here.

The number of papers and level of details depends on multiple factors:

1. Industry

If you are dealing with avionics or automotive you need to produce zillions of documents and reports, some of which may be required by the external certification committees.

On the other hand, if you are doing simple web app, a single diagram may be enough.

2. Customer

Some customers require you to produce multiple reports from the development phase: design documents, test reports, performance reports, license compliance reports etc. Not much you can do about it.

3. Size of the project

Any complex system, may need documentation on multiple levels: general system overview, specific components documentation, internal APIs, public APIs etc.

Simple projects are usually good with the general overview.

4. Team structure

If you work with localized team with great rotation of team members or your team is spread across multiple locations, you may want to create overviews, guidelines, wikis etc. It is really wasteful to start every quarter of a year with giving new members training on basics.

Summary

I know that maintaining documentation is troublesome, but that is why I am not asking to document all the code, with all the internal APIs, etc. Especially, when cooperating within a small team or small scale project. The minimum we should be doing is to note down what kind of problem we are trying to solve, and how our software is going to help us. Then architecture overview, few diagrams may be enough.

Writing down ideas will give us time to re-think possible options and get feedback from others.

Let’s not be scared, few papers won’t bite.

Posted on by:

mdabek profile

Marek Dabek

@mdabek

failing robot in polish trenches

Discussion

pic
Editor guide
 

Great rundown. We've never been sure about what and how much to document.

 

Thank you! I hope you can get some hints from my post.

 

I've mentioned this elsewhere before, but I think it bears repeating. At my company, we have some simple rules:

  • README describes WHAT your code does.

  • Comments describe WHY you wrote the code the way you did (intention).

  • Documentation describes WHAT your code does (in detail) and, more importantly, HOW the user makes it do that. API docs do NOT count here.

  • API docs may be useful as internal reference for developers, but not for end users. As I've said before, "most API documentation is like teaching someone how to use a toaster by explaining the electrical specifications of the heating element."

(All that from my article [Your Project Isn't Done Yet][1])

dev.to/codemouse92/your-project-is...

 

I have doubts about your approach to API docs. One of the assessments I am doing, when selecting a piece of software is reviewing the API, which gives me a rough idea about what the software is capable of.

 

Sure, there may be other reasons to have API docs. The problem is when these are offered as full replacements for end-user documentation...which is exactly what happens in a disgustingly large number of projects.

At the same time, if you're having to read the API docs to figure out what the software does, it means someone didn't actually document it properly.

 

I agree with your general point: dropping all documentation is usually not a good idea. Some documentation is useful. You also provide examples that I can agree to: "a high level overview, and some guidelines, and tips&tricks".

There are some statements in your text that I can't agree to. Like this one: "First of all, an engineer is only a part of a delivery chain. It is really rare that an engineer (or team of engineers) provides a final product. "
Do you think that it is rare that a team of software developers programs, tests, releases and maintains software on their own, given the requirements are known? If that's what you mean, I think you are wrong. I have witnessed many teams who do that successfully.

"Ideas need to be somehow communicated, assumptions must be made and limitations must be discovered. What is the better way to think about them and share our discoveries than writing them down?"
In some cases, a better way may be to talk to the other team members directly.

Related to the bus factor: do code/design reviews, and pair programming. That way, you can reduce "knowledge silos".

Documentation can be useful. But there are other ways of communicating WHAT the code does, including structuring it consistently. So the question is not: should we document or not? But rather: for whom, for what and how much?

 

Thank you for your comment.
As an engineer I can assure you, that I highly appreciate work being done by fellow engineers :) I agree, that the "delivery chain" part may be unclear.
I see software as a mean of solving some specific set of problems. Software can be a tool (e.g. CAD, trading system), a part of a tool (e.g. infotainment system) or rarely a complete product by it self (e.g. video game). If you think from this perspective, you see that there is more than a team of engineers, first of all there are customers, next, business side of the project, marketing etc. Clear communication between these parties need some sort of common platform and it may be really difficult to gather all of them in single place to give a talk (and probably you would need to prepare slide deck for that - still a documentation;))

 

Indeed - informing all relevant stakeholders can be a challenge. Thank you for the answer.

 

I appreciate you calling out that every project is different and requires different types/thoroughness of documentation.

 

Yea the agile manifesto has made us a bit lazy with documentation. Good read