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

New online tutorial: User Stories

This blog and my email updates have been quiet lately because I’ve been working on some online tutorial (in addition to working with clients!).

These tutorials differ from my earlier work in that they are autonomous, self-paced, async – I’m not there! – truly online.

Just my voice, my slides, my exercises and my wisdom.

At the moment there are two tutorial, “User Stories by Example” part 1 – an introduction and part 2 which looks specifically at acceptance criteria. Both use actual user stories I’ve collected over the years and both are derived from the online interactive workshops I ran during lockdown last year. Those workshops were themselves based on a physical workshop I’ve been running for several years, which in turn is based on my Little Book of Requirements and User Stories book.

I have plans for more tutorials covering user story refactoring stories (i.e. improving existing stories), story lifecycle and workflow, splitting stories and appreciating value. First I’ll wait for more feedback on these first two.

I’ve set introductory pricing at $59 and $49 (USD) but I expect those prices to rise as I add more modules. Part includes both the e-book and audio book version of Little Book.

Blog readers can get another 20% off with the coupon code “blogdiscount” until the end of July.

I’d love to get your feedback on these course so if you try one please complete the survey at the end and e-mail me if you have other comments. And if these courses are not for you, well, please e-mail me anyway and tell me what you would like to see me produce next.

Cascading OKRs and White Space OKRs

A couple of weeks ago I blogged about the top-down or bottom-up question – “OKRs top-down? bottom-up? or ripples on a pond?”

The idea of top-down OKRs keeps cropping up: it needs a name. So please let me introduce Cascading OKRs, or C-OKRs for short.

I only just invented the term so I don’t use it in Succeeding with OKRs in Agile – although I do warn against the idea. The meme is in books and blogs I’ve read, in podcasts I’ve heard and it comes up again and again in Q&A sessions when I do presentations.

The Cascading OKRs idea goes like this: the people at the top of the organisation set OKRs. These are shared with people and teams “below” them. Those teams then write OKRs to support the delivery of the those above them. Their OKRs are in turn shared with “lower” individuals and teams who repeat the processes.

I’ve even heard it suggested that teams take the OKRs from above and use the key results as their objective(s). The key results they create around these objectives can then be used by “lower” teams as their objectives. Hence OKRs cascade down the organisation. (And we all know what Cascades look like don’t we?)

Undoubtedly this interpretation has its own logic – both in the top setting the master OKRs and the lower levels implementing them. It is after all functional decomposition. And I must believe from what I hear that some companies do it this way even if I have never seen it myself. One hopes that it works for these companies, I think it can be better.

C-OKRs are incompatible with the agile mindset because it deprives teams of autonomy. Each team must implement the objectives given to them regardless of what the team believes, regardless of what the team’s customers are asking for, irrespective of the research the product owner/manager has done.

In reducing, even eliminating, autonomy motivation is going to fall too, teams are no longer their own masters.

Nor will this way increase agility because each team must move in lockstep – or perhaps one step behind – the team above them. The cascading hierarchy injects delay.

Cascading OKRs may be easy to grasp, they may be easy to sell, they may follow the logic of hierarchy and management-by-objective but that also means they represent a lost opportunity to integrate OKRs and agile.

Having named Cascading OKRs I need to name the alternative: broadly the approach I advocate in Succeeding with OKRs.

I name this approach White Space OKRs, WS-OKRs.

Organisational leaders should set the vision, the big-hairy-audacious-goal, the ultimate objective, the massively transformative purpose. They should name the mission, they should set the culture and talk about the purpose of the organisation.

And they should leave copious amounts of white space – space for teams to fill.

Those visions should be light on how; they should be light on orders, instructions and mandates. That may seem odd but only by leaving these things out – by leaving white space – can individuals and teams, at all levels, decide how best they can support that mission, goal, purpose or whatever you call it. Planning is disabling.

Because teams decide how to support those goals – while supporting existing customers, legacy business and technology, plus other (potentially completing) demands – team retain autonomy, and autonomy creates motivation and flexibility.

There is one more assumption underlying this which deserves mentioning.

White Space OKRs assume that the teams already exist. With WS-OKRs leaders don’t need to create new teams to deliver their goals because those teams already exist. In other words, the organisation is operating a post-projects model, e.g. product teams, continuous digital, Spotify, or maybe SAFe. That raises an issue of gaps and I’ll return to this another day.


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


White space photo from Katie Doherty on Unsplash.

Sorry about the OKRs

Quick word of appoogy to regular readers who may not be interested in OKRs: sorry for all the posts about OKRs.

Its probably a natural effect of pubishing a book on the subject and then doing a bunch of presentations, webinars, workshops and Q&A sessions. Give me a few weeks and this will pass. Normal service will be resumed, with thoughts on agile, technology and such – I just don’t know when!

Our brains want more but less is more

Less is more – I say it so often but it is still a lesson I still have to relearn regularly. Go small. You could say that my most famous blog post is saying just the same thing in fancy language – Software has diseconomies of scale – not economies of scale.

So a couple of weeks ago I was fascinated to see an article in The Economist entitled “Why people forget that less is often more” (paywall) reporting on research published in Nature “People systematically overlook subtractive changes” (another paywall) – being Nature one knows this is serious science.

The researched showed that less is more applies mentally as well as physically. That is, people are far more likely to solve problems by adding elements than by subtracting them – even when subtraction is both viable and costs less (some of the experiments introduced the idea of cost.) The researches even go as far as to suggest this isn’t just a case of believing the additive (more) solution is better than the subtractive, it appears our brains are less likely to consider the a solution which subtracts elements to create a solution.

Last year when I was struggling to complete “Succeeding with OKRs in Agile” I found a solution in removing some chapters. Some were little more than notes, some were in draft and a couple were fully written (and edited). Removing those chapters made the book less, but it made my work load less too – which had an immediate benefit.

It also meant I could finish the book sooner. It meant the copy editing process was quicker and cheaper, and it meant that the book could be published on Amazon and start earning for sooner. But I also believe people like shorter books, I really believe that I’m selling more books because it has less than 200 pages than I would if it had over 200, let alone 300.

This has a bearing on the way companies organise themselves and their processes too. When I first started talking about #NoProjects (which became Project Myopia) I really saw this as a “just remove the project model” – keep doing all the other stuff but just drop projects. Part of me still believes that and while I recognise that some places need more structure I also believe that adding projects is simply overhead for many small companies.

I see it too in the “fear of coding” that many companies have – don’t let people code! Plan it, write it down, estimate it, find the cheapest supplier, argue about it – when simply doing it would be cheaper.

I see it too in the way “agile methods” have grown. Scrum, and XP, are barely viable development models. Compared to RUP they are miniscule. But they worked. Before agile we called them “lightweight”.

Now we have SAFe and other frameworks which bring big thinking back. Nobody would call SAFe lightweight – not with its 10 principles, four configurations and five versions. Perhaps we should have stuck with “lightweight development methods.”

I think it was Alistair Cockburn who once said “Traditional methods are tailored by removing elements, agile methods are tailored by adding.” If the research above is right it was only a matter of time before someone created an “agile method” as big as SAFe.

Finally, another example of less is more: I could write more in this blog but less is more.


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

OKRs top-down? bottom-up? or ripples in a pond?

One of the great things about writing a book is that you get a greater understanding of the subject. So it was with “Succeeding with OKRs in Agile”. In particular writing the book forced me to think about how OKRs fitted with agile and hierarchal structures. I get the impression that many people are interested in using OKRs to align teams but not everyone has worked out all the nuances.

On the face of it OKRs are hierarchal: it seems “obvious” that someone, somewhere, is going to set a big goal, that goal will cascade down and every team will end up with their own mini version of the goal. As I said, this seems obvious, how else could it be? Especially in a large organization?

After all, is that how the not so distant ancestors of OKRs, Management-By-Objectives (MBOs), worked.

This also fits the engineer’s mind: the product team have a goal, and all the supporting teams – whether contributing components or services – make their goals subservient to the one goal. The classic inverted tree with each team doing what the node above asks.

But, top-down conflicts directly with reality and with agile. Teams don’t have one goal, they don’t answer to but one leader but to multiple leaders, multiple customers, multiple stakeholders and these don’t always agree. Agile folk have long railed against command-and-control from above while advocating self-managing or self-organising teams. Surely OKRs go against this philosophy?

So, if we are to use OKRs in an agile environment these positions need to be reconciled. In Succeeding with OKRs I described the process as more bottom-up than top-down. Thus, rather than a big boss saying what should happen and that being cascaded down the origanization to provide goals at every level, I describer the big boss setting out a vision, a goal, an objective but not describing details. Then they say to the teams: “Help, how can you help more us towards that goal?”

Now, only a few months after I wrote that my thinking has moved on. I don’t disagree with myself but I see the need for a more nuanced explanation and a revised model.

First off, I’m guilty of using the language of hierarchy: top-down and bottom-up. In so doing I’m supporting the view that hierarchies are the natural state of things and creating a, possibly false dichotomy: one thing or another. For years I’ve been thinking of organisations both as federal entities and as solar systems. While the leadership team may be central to decisions they are not all powerful . Teams have their own paths, leadership and leadership teams are the sun and teams/divisions orbit them. (If I recall correctly I picked this idea up in the Henry Mintzberg book Simply Managing.)

Bear in mind, as I say in everyone of my books: team are autonomous. We stive for independent teams with devolved authority. Each team exists to deliver a product or service and each team has multiple stakeholders – of whom the big boss is but one. Each team therefore has to decide how best to deliver benefit to (potentially competing) stakeholders. Sometimes that means co-ordinating with other teams and even other companies.

Put that together: teams are creating OKRs but they are not doing it in isolation, they are listening to the big bosses at the centre but also the teams they need to work with.

Recently I’ve started to think of these concentric circles less as planetary orbits and more as waves, or ripples to be precise. The big boss at the centre makes big ripples that carry out to the edges.

But leaders are not the only ripple makers. Teams, customers and other stakeholders also have an effect – like rain falling on water. Sometimes these waves some together and magnify each other, other times they cancel each other out, more often than-not they are out of sync and disrupt each other in ways too complex to predictable.

We think of leaders as single water droplets but inreality there are lots of drops making lots of ripples

OKRs are the messaging system that allows teams to signal what ripples they are creating and which they are reacting to. Teams are iterating – OKRs reset every 13 weeks – which means every quarter teams get a chance to react to other ripples and rest their own.

Thought of like this you also get a scaling model. Not so much a model of “how to do this to scale” but a mental model which describes how to think about scaling.


I have some upcoming presentations and webinars about OKRs if you would like to know more

Or, buy the book “Succeeding with OKRs in Agile”


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

Presentation & speaking engagements

Agile on the beach

The attention Succeeding with OKRs in Agile has got means I’ve had a lot of invites to speak about, well, Agile and OKRs. So I am at a number of meetup groups and conferences, and odd conversation, over the next few weeks, most of which are free to attend online.

An up to date list of public speaking engagements can always be found on my website. In addition to public speaking I regularly deliver private presentations too. So please get in touch and book a date your team or company.


Reawakening Agile with OKRs

When: 6 May, 5.30pm Sydney, 8.30am London

Online presentation

Organized by SAFe Sydney, free, booking required


Reawakening Agile with OKRs

When: 11 May 2021, online presentation

Organized by BCS Change Management group – booking required (free to attend)


Succeeding with OKRs

An online conversation with Adrian Reed, 20 May 2021.

Organiser and booking with BlackMetric


Reawakening Agile with OKRs

When: 27 May, online presentation

Organized by Cambridge Agile Exchange, free, booking required


Reawakening Agile with OKRs

When: 30 June 2021, online presentation

Organized by Future of Work in Scotland, booking required


Allan Kelly at Agile on the Beach
Allan Kelly at Agile on the Beach

Reawakening Agile with OKRs at Agile on the Beach conference

First live, in person, event since March 2020 – with beach party!

Sept 2, 2021, tickets on sale now