We really should write this down somewhere!
Consider this: You're trying to use your company's new FooBar webapp, but after you got "onboarded" by the people running it, you just end up with a link to a confluence space. There a mountain of text leads you through how it FooBars. A cursory clickthrough reveals a web of 194 interlinked pages. You're overwhelmed. You also are a bit terrified about what will happen once you visit the actual FooBar url.
By the way... Where is it?
Oh yeah page 13. In the environments subfolder. Okay, "Here we go" you exclaim, thinking internally "Am I going to FooBar correctly? I didn't read the other 12 pages before, nor the ones after..."
The FooBar app's webpage opens. Hang on! This doesn't look anything like the screenshots on those confluence pages...
There are two things that are extremely difficult in software development:
(Oh, yeah, and off by one errors of course!)
Focusing on documentation, it can go many ways. You and your team could go "Yeah, its a ll self documenting" and do nothing. (Which might actually be the less bad choice!) On the other hand, it is just as easy to get carried away. Everything is important, right? We feel the need to document every function, every feature, every possible use case. And what about the different strata of documentation? Design decisions, infrastructure, the code, business logic, team processes, miro boards, business analysis, team setup, figma mockups, your dentists haircut, Per-SonaS! That should all be written down somewhere! Right? And then we update it every time anything changes. Everywhere. Right? Right....?
As a famous fictional character once said, "It's not the size of the manual that matters, but how you use it.". If your FooBar requires extensive documentation for users to understand it, perhaps the issue lies not with the documentation but with the implementation. Great UX/UI can let you get away with lots of things, even documentation. In my experience, priming a first time user with one or two sentences about how an application works can be enough for them to have a good onboarding, as long as the UX and UI allow for self learning.
A common complaint I witness is that moving information across multiple platforms (Jira, Miro, Confluence, git) is the cause of documentation requiring high effort. And sure, it is true. Having multiple tools in a team's or an organization's workflow not only creates redundancy but also increases the chance of inconsistencies and the interconnections that need to be kept in sync.
It is hard to think of teams I have worked with that didn't have a situation of "Yours doesn't look like mine" across tools at some point. But here too there are ways that can help keep noise down and friction absent.
On the extreme side, I often challenge teams to find out if they could actually reduce to jsut one source of truth. Not one SVOT per "thing" (design, engineering, pm) but actually just one place where content exists. In terms of software producing teams, this would minimise their content footprint to just one git repository (Hi there multi repo crowd! Yeah, I've noticed your raised pitchforks, no need to get blodthirsty here). But again, this is more of a thought excercise in minimalism than anything else.
While this is a great excercise and I would invite anyone to give it a serious effort at least once the truth is that at some point you inevitably will be forced out of this system by corporate or business reality. Nevertheless, it can teach you and your team a lot.
On a more pragmatic level and by still keeping the core philosophy of minimalism, I have found that designing a team's work process in a way where information flows only in a single direction and using that process definition as the core of their own documentation can be helpful in the long run. Not only does starting with the process get everybody zeroed in about their position in the system and the qualities of the information that get to them or are expected of them, it also makes it easy to discern where documentation might be meaningfully placed and allows outside consumers of that documentation to get much needed context.
This can also be expanded to include non Ops documentation. Instead of documenting every tiny detail, focus on the essential workflows and the concepts they work on. Understand how information flows through your system and document that process clearly and concisely. This approach not only makes your documentation more manageable but also ensures that it remains relevant and useful. Often, when moving to such a model, you will find that a lot of prior documentation doesn't have a good place any more. It can be that your process definition is missing something or that your UI/UX has improvement potential, but more often than not, this is documentation you can safely delete!
Minimal documentation is easier to maintain and update. When you have less to keep track of, you’re more likely to keep your documentation current. This is crucial in fast-paced environments where changes are frequent.
Documentation is essential in IT and software development, but often, less is more. As the saying goes, "Keep it simple, stupid."
For more insights on this topic, check out our previous posts on The minima we enter and If you have to name it, maybe you are doing it wrong.
