Documentation, another case of rapidly diminishing returns

No body writes documentation in startups.

Writing documents is a luxury only established companies can afford. One might ask: are companies successful because they write documents or do they write documents because they are successful? But I’d be hard pushed to find anyone to argue the latter.

Back in 1996 I worked on the ill-fated UK rail privatisation. I was part of the team writing a new computer system to create a new rail timetable – one that would allow competition in train services. In the average week I spent half my time coding and half my time documenting.

For every program there was a program specification – what the program had to do. And a functional specification – saying what the program did. I had to update both. And these had to align with the system architecture, which was a multi-volume beast I wasn’t allowed to touch.

Additionally I had to create a unit test plan for each program or set of changes. Unit tests were manual and the test plan was made up of two Word documents. One was a big table and the other had one test per page. As I conducted the test I had to update the plan with success or fail – and fail of course mean rework so we alwys made sure it worked before hand.

When my program was ready to check-in I had to fill in a source code control form so my team leader knew which files to check in. If I added a new code file to the system I needed to complete an additional form to explain what the file was. On one occasion I got fed up of a 2,000 line C++ file and refactored it as 4 smaller files. Being C++ his meant 4 pairs of .h and .cpp files, so 8 new files each with a form. My team leader was quite clear: I was never to do this again, it made too much work for her.

Did it help? – I find it hard to imagine it did. In fact I started my own hidden documentation, the “Rough Guide to …” which told me (and other devs) things we actually needed to know.

There are two types of companies: those that don’t write documents – and where many many people are asking for documentation. Documentation is seen as a solution to (almost) any problem. And yet people don’t write documents, then they feel guilty about not writing them.

The second type of company is overrun with documentation. There seem to be armies of people writing documentation: architects and business analysts seem particularly keen to write documents. These are often prose, they are about as readable as your average Shakespeare play is to a 15 year old and read about as often. Project managers are also prone to documentation but they don’t write prose; instead, project plans and progress presentations are documents in another medium.

In the first type of company nobody reads documents because there are none. In the second type of company its debatable how many of those documents are read. Many of them are so utterly boring that it is hard to stay awake reading them. As I’m often heard to say:

The bigger a document is, the less likely it is to be read.

And if it is read, the bigger a document is the less the reader will remember.

In one eye-and-out-the-other.

It’s probably just as well because documentation rapidly becomes out of date unless copious amounts of time are invested in keeping it up to date. Actually, it is good that documentation is seldom read because reading it is almost as expensive as writing it and, in theory at least, it should be read far more often.

True, “documentation” covers a very wide range of things. From project plans to release notes, from user guides to architecture diagrams. Some has more readers more than others – user guides compared to functional specifications. But then, who has read their iPhone manual? Does such a document even exist? Arguably the best products don’t need documentation.

In both types of companies I hear complaints about the lack of communication – actually, I don’t think I’ve ever visited a client were people didn’t complain about the lack of communication. But only in the first type of company do people think that documentation will cure the problem.

In such companies documentation is seen as the solution to almost every problem. Programmers complain they haven’t been given written requirements and specifications, they complain the user designers aren’t giving them documents of is expected, and most of all they complain the developers who came before them did not document what they did. Equally testers demand the same requirements and specification but also want programmers to provide written descriptions of what the program does. Project managers want written reports of what was done and so on.

Nobody ever got fired for asking for more documentation, but I’m not so sure about writing it.

While I have sympathy that these people want information I don’t believe documentation will solve the problems – perhaps because I’ve never seen a development effort with “Goldilocks documentation” – not too much and not too little. One thing I do know is that if everyone wrote the documentation they thought was needed, and what others wanted from them, then little would get done.

What I fear is a descent into documentation as everyone sets about communicating through documentation and not talking.

Because documentation takes time and money to create, it takes time and money to read, it takes time and money to update and keep current. And all the time and money spent on documentation is time and money not being spent on developing products and testing products in the market.

Worst still documentation becomes a hinderance to change. On multiple occasions I have met companies that do not want to change their products or processes because the cost of updating the documentation is too great.

I’ve nothing against documentation itself, I simply lament the time and money that could be better spent elsewhere, I regret the missed opportunities for real communication and belief that something has been communicated; and I fear the limitations that documentation brings once in place.

To answer my own question above. I don’t believe companies that write documents are successful, documentation does not determine success – if it did many many projects would have succeeded instead of failing. That documentation is so often lacking but products are successful actually goes to prove that is not essential.

Nor do I really believe companies write documents because they are successful. They write documents because they are successful enough to be able to afford to write documents but those same documents inhibit future success.

Before I close, I can almost hear people rushing to their keyboards to tell me of occasions were a system document saved their life,

“If Sam hadn’t left behind a document that told me the function was connected to the reactor core…”

While I’m sure such cases exists I’m not convinced the they justify the vast amounts of cost of writing a document against doing something else. If Sam hadn’t written that document what might Sam have done with the time instead? Possibly something even more valuable.

As with planning documentation exhibits rapidly diminishing returns on investment.

Photo by Glenn Carstens-Peters on Unsplash


Subscribe to my blog newsletter and download Continuous Digital for free – normal price $9.99 / £9.95 / €9.95

User Stories by Example part 3 (Refactoring)

The latest instalment of my online User Stories tutorial is now available online, User Stories by Example: Refactoring.

It takes as its starting point some existing stories and reworks them to convey their message more clearly. In the process I discuss:

The use of time-boxed spikes.

The naming of team members in user stories, e.g. “As a developer I want …” – and why this isn’t a good idea.

Rewriting user stories and breaking them down into more smaller stories. (More on this in the next tutorial.)

Why more smaller stories is better than a fewer larger stories.

How acceptance criteria can be used to split stories into smaller pieces.

and a brief look at dealing with dependencies.

Videos are intersperced with exercises and quizzes. My guess is this tutorial will take two to three hours to complete – which can be all in one go or split over days or weeks to suit yourself. As with the earlier tutorials I work through real life user stories to illustrate and draw lessons.

This is the third tutorial, it joins User Stories by Example part 1 Starting with Stories and part 2 Acceptance Criteria. The next module will look at splitting stories in more detail.

The tutorial this carries the introductory price of $49. In time this price will probably rise and I’ll introduce a combined option to buy all the courses in one go.

Please e-mail me with your comments and suggestions.

Software is not a lump or work to do (and the laws which prove it)

Workers digging hole

Building software is not like digging a hole in the ground: your target changes as you dig, the people and machines you use change the outcome beyond the original idea, and you never really know when to stop digging.

Years ago I was hired by Reuters to build an interface connector between the Liffe trading exchange and their data systems. Another developer started a few weeks after me. In the end we produced about half a dozen modules that worked together to make the connection. But we only produced that many because we were over staffed. In reality the one module I wrote handled 90% of the work required, the other modules were largely superfluous. And certainly the extra time which would have been required to make my module do 100% of the work was less than the time I spent to making sure it worked with the other modules.

Regular readers have probably already recognised Kelly’s Second Law of software: Inside every large development effort there is a small one struggling to get out

This itself is an example of Parkinson’s Law: work expands so as to fill the time available for its completion.

Actually you might restate my second law as Parkinson’s Law in reverse: constraining the capacity to do work reduces the amount of work to do. If you think about it this is a result of Conway’s Law: system designs copy the communication channels in the organization which creates the system.

Economists see a related phenomenon as the Lump of Work fallacy: people assume there is a fixed lump of work to do. If there are more people to do the work (say from immigration) then there will be unemployment – or possibly wages will be forced down and same work is distributed between more people. However at the level of a national economy it doesn’t work like that. More people means more demand for food, houses, healthcare, schools and so on. What is true in the small is not true in the large. The net effect can be positive for countries but exactly how and by how much is hotly debated.

Software development has its own lump of work fallacy: There isn’t a fixed amount of work to do. Rather than saying “How many people will it take and how long will it take?” It is better to say “If we have five people working on this for three months what progress can we make?”

Writing software is not like digging a hole in the ground: the work to do is neither really known in advance nor is it fixed. Adding people actually increases the amount of work to do – Brooks’s Law.

At the start nobody really knows what it required, they may get lucky but more often that not once the thing is put in front of clients and (potential) customers the ask changes. I’ve heard this called Humphrey’s Law (after Watts Humphrey) although that name is not in common usage and there is another Humphrey’s Law from the world of psychology – which is connected with time estimation discussions for different reasons.

When you put Parkinson’s Law together with this “don’t know until I see it” law you get Hofstadter’s law: It always takes longer than you expect, even when you take into account Hofstadter’s Law.

Lets assume for the moment that one can know what is wanted in advance. There is another problem: there are multiple ways to achieve the same result. There is no one true way in software development, there are always multiple ways to achieve the same end result.

Even if one was to fix the big questions – the OS, the delivery platform, the programming language, the database and so on – then you can still create very different implementations for the same thing. Or as I usually put it “there are many ways to dice the onion” – my Crown Jewels post describes how I can get wildly different time and money estimates for what is basically the same piece of work.

Of course this has big consequence for effort estimation – how can anyone estimate effort and costs in these circumstances? Let me go further and suggest that the process of estimating the work to do is more likely than not to increase the amount of work to do. Not only does estimation take time to do itself, but there when estimating there is a tendency to “play safe” and favour larger estimates even thought these estimates are likely to themselves be underestimates (see Vierordt’s law.)

Sometimes it feels like quantum physics: when one parameter is measured another changes, we can know the speed but not the direction, or the direction but not the speed.

I’m not sure I have a complete answer but I have some of the pieces.

Start new work with a Minimally Viable Team: task the team to start immediately, coding starts on day one and in parallel the team work to understand what is needed and create potential solutions.

Keep teams stable: Teams and staffing containing a lot of variables, keeping the team stable (but not static) provides some past performance data to include in calculations. It will at times be necessary for the teams to call in more help – pull more skills and resources as needed.

By working with existing and minimally viable teams the problems are partially constrained: the technologies available are mostly the technologies the team knows already, the number of people available to work on the work is the number of people on the team. In time you may change both these parameters but initially they are constraints to work within.

Lastely, use active portfolio management and governance to kill work which is under performing or escalating beyond expectations. You may want to engage in set-based engineering to increase the chances of success.

The next time someone says “Building software should be like building a house” please remind them you aren’t building a house. What software engineers do is massively more variable and complex than building another example of the same thing.

Back at Reuters, the bright side was that the over engineered system we built wasn’t just used for Liffe, it was used to connect 2 or 3 other exchanges too so maybe the over staffing and over engineering was worth it. Except I don’t believe it really made economic sense, it would have been better to get the one exchange working and only add the minimum to the system when the second and third exchanges came along – diseconomies of scale again.


Subscribe to my blog and download Continuous Digital for free – normal price $9.99/£9.95/€9.95