Lean Documentation: Map the territory without docrot
Ah, documentation rot. If anyone in either IT or the startup world can say they never spent a long time sifting through documentation that was mostly out of date, often so detailed it wasted too much of your time, and often enough didn’t even touch on the important points you really wanted to know — you’re either lying, or just not remembering it right.
Documentation is important. For code, for processes, for business logic, and more. Without any, it’s hard to introduce new people to the environment, for people who already know it to refresh their memory on the specifics, and even for the people who built it to make sense of it a year later. With insufficient documentation, things will change without good reason (that is, without improvement), just because someone didn’t know how they were supposed to work.
To be brief: keep it brief
I’m going to save you reading the rest of the article: keep it short, keep it simple, and keep it useful. There. You can close your tab now. Maybe scroll to the end and give us a 💚 first.
Still here? All right. The thing is, the longer and more detailed your documentation is, the more you’ll feel good about it when you’re done writing it; the harder it will be to keep up to date, the more effort it will take to read it, the less likely it will be that anyone bothers to, and the less useful it will be. Oh, yeah, and the harder it becomes to find the information one needs.
So, take to heart the big Agile maxim: write the simplest thing that solves your problem. Let’s call it the “Minimum Viable Documents”.
And if you find your MVD is still not very minimum, that’s also a risk indicator. If any of your individual bodies of documentation (code, process, company structure, technical infrastructure…) takes an eager reader more than half an hour to read through, that means the topic is too complex and needs cleaning up. If it takes more than 15, consider it a red flag already. It’s always better to cut code and simplify architecture than to document it.
(Especially true of processes! Those should take 5, maybe 10 minutes. If it takes longer than that, the process is almost guaranteed to break.)
API documentation: keep it in the code
JSDoc/PyDoc/Doxygen/JavaDoc are your friends. Write your API documentation inline, following the standardized format for your language, and extract it using one of these tools (or whatever is equivalent if you’re using some other language). This way you’ll have a browseable version of the docs, but also the documentation right there in the code, for people to read. And being right next to the code reduces the odds it will become out of date (when someone updates the code, it’s easy to update the comments/docstring/tags with it).
There are two things you should do to keep it up to date: first, set a policy that they have to be kept up to date, and enforce it in code reviews. But more importantly, keep them brief. The longer, more verbose, and more detailed they are, the greater the chance they’ll be outdated, and the less useful they become (it’s often easier to just read the code than a full-page wall of text).
And don’t automatically assume you need it at all. Having brief, clear, intent-oriented code, with very short methods, beats a well-mantained API documentation — the code will be its own documentation, and enforcing this encourages developers to write clear code.
Process documentation: what would David J. Anderson do?
In the Kanban book, David J. Anderson gives us a very useful definition of process:
It is important to think of a process as a set of policies that govern behavior.
The title of the chapter in question is “Make Process Policies Explicit”. So, don’t just tell developers, “we do Scrum”. Every Scrum or Kanban implementation is different; that’s part of the official definition of both methodologies. Write down your process as a list of policies, from the obvious: how long are our sprints, when is the stand-up, how do we structure work items (epic/story/task?), definition of done, etc; to the trickier: how do we track and handle impediments, how are tasks assigned (do you take the first one available? Divvy up in the stand-up? Team lead assigns?), who prioritizes and schedules bug fixes, and so on. Kanban? Document your classes of service, WIP limits, queue-filling method. If a new hire asks you a question about process, consider adding it to the document.
And then there’s everything else: coding standards, code review policy, vacation scheduling, and so on.
All process documentation is a list of policies. Use technology in your favour: put these policies somewhere indexed, so they’re both easily searchable and easily browseable.
To hammer on my mantra (and mix my metaphors): keep them simple and short. If a policy fills half a page, it either can be described more briefly, or needs some simplifying of the policy itself. My recommended format is a brief Q&A format; for an example, keep reading — I used this format for the next section.
Overview documentation: keep it high-level
The most important bit of documentation you need is the overview documentation. This is what new team members will refer to in order to onboard themselves, and everybody will refer to at times, either to refresh their memory, or figure out the consistent way to introduce something new.
This style of communication applies to architecture overview, infrastructure, and company structure, for example. I’ll describe it assuming we’re talking about code/architecture, but I trust you can translate it to other uses.
What are the main components? How are they connected? A diagram and a few paragraphs explaining it. We’re talking high-level here, not individual classes. Even if yours is 10× more complex than the example in the picture, this is probably the most important part of the documentation, and the one new people will want to see first; it helps form a mental picture of the system as a whole, and it allows one to figure out how to proceed with studying it.
I listed some third-party libraries in my example (and colour-coded them green to indicate they’re third-party), but that doesn’t mean you want to diagram everything you use. Those would be the ones at the core of your business logic, the ones which should be understood in order to make sense of the system: if you’re manipulating 3d models, for example, the one you use to handle file formats, the one for geometry, and so on. You can list frameworks that way, but I prefer to put them inside the component boxes as you see in the example, since it’s an indication of nature — “this component is an Angular-based application”.
Don’t mix your code/architecture and infrastructure documents. You want a separate body of documentation (in the same style) with what servers run what where, how the deployment system works, build system, test runner, etc. There will be an overlap between diagrams (in my example, database, back-end, daemon). If possible, keep a visual link, like the colour coding, so it’s easy to relate the two documents.
What do I need? In the case of code, links to the repositories, versions and links of tools and libraries that need to be installed, etc. Ideally, automate everything, so for each component, you can reduce it to: “Check the code out from <repository link>, install <node/python/ruby/java> X.Y and <npm/pip/gem/maven> X.Y, then run <one-line environment setup command>”.
How about something completely different? For company structure, this would be mostly who do I need. Who to talk to about HR issues, office equipment, office infrastructure (the coffee machine broke!), IT support, etc etc. And then the stakeholders and contact points for the different departments. Don’t tailor it to a specific department or function! A single, brief, well-organised company structure document for every company member, whether developer, sales, receptionist, or product owner. Even if some people won’t need most of that information in their daily work, it’s still a Singe Source of Truth, enabling everyone to speak in the same language.
How do I use it? For code, instructions to build and run it. Developers are pretty good at reverse engineering how code works, but for that it needs to be running; figuring out how to get it to that stage can be very frustrating.
What are the related policies? Refer to the section about processes above. What parts are relevant here? Coding standards, UI style guide, code review policy. Ideally, those should be part of you process documentation, and not the code overview; here, you’ll just have links to it.
Who can help me? Momoka is the expert on 3d model manipulation, John knows MongoDB like the back of his hand, Paul and George can answer your questions about the back-end, Paul and Ringo for the web app, Charlie was the original mobile app developer, and oh by the way George is really good at iOS.
Rather than trying to predict every possible thing someone might want to know and write it down, stick to the high level and write the MVD, then point them to an actual human being who’s likely to know the answers to anything else. For onboarding purposes, this has the added benefit of providing excuses to talk to colleagues and start forming bonds.
This section also gives you an alarm system for knowledge drain: should Charlie leave the company, you’re left with no deep understanding of your mobile app, which will probably cause all sorts of problems. Make sure Charlie hands over that knowledge before leaving.
This is it. Don’t be tempted to add more. For sure, I’m not omniscient; your project or organisation might have some needs I haven’t foreseen. But think about it very carefully before getting keyboard-happy; discuss it with one or two colleagues; consider whether it wouldn’t be better to just leave it to face-to-face communication. Consider how much work it will be to maintain it and how likely it is to become outdated.
Document all the things
You’ll note I referred a number of times to a company structure document. It’s one of my favourites: most organisations leave it to members to figure out the hard way who is who and who to talk to about what. Often, the “onboarding” policy includes an introduction to the people responsible for two or three things they’re likely to interact to (e.g. the PO, the head of QA, and the lead designer). Sometimes even worse: the names are written on a whiteboard, possibly in a diagram, and no clue on who the person is and where to find them. And then what happens if they have a problem with their computer? Something to clarify with HR? Broken chair?
Your organisation is a system as much as your code; usually as complex as the code, or more; and one every member will have to “use”. Having no documentation for it is just as bad as undocumented code. And just like code documentation, don’t attempt to predict what parts your “user” is most likely to interact with: document everything, but from a high level, and make sure it’s easily understood.
Oh, and use photos if possible. Remember many people are terrible with names, and there’s already more than enough set up in our society to shame them. Anecdotally, in my experience, the average person needs to meet someone about 3× in order to remember their names, and when introduced to more than 5 people in the same day, will remember at most 2.
There are many things an organisation should document (briefly and clearly!) and most don’t. Public communication style. Recruiting process. Sales pipeline. If you’re a Lean Startup, document your hypotheses and their tests — both currently running and historical with results — then make the whole thing available to everyone in the organisation, to advisers, and possibly also investors. I have a whole other article in my write queue about documenting your value stream so team members can understand why they do things. So: as a leader or coach, if you see any topic that causes confusion often enough, consider if it should be documented.
Lean documentation is a question of writing less about more: keep it simple and clear, but write about everything — make policies explicit, and information easy to find.
And always include a human point of contact, in case of questions.
