15
Big Signs That Your Documentation Stinks.
Why is it that we freely admit code smells, but get a tad bit defensive when the usefulness of our documentation is called into question? I've been pondering this, and I think I have a theory:
As a senior developer and engineering manager who has worked on quite a few "death marches" in a 20+ year career, and with a strong background in developer communities .. I can confidently say that the graph isn't too far off.
We don't necessarily feel personally attacked, it's more of not wanting to be reminded of all the junk in your basement that you need to have cleaned out before your in-laws move in. And maybe you don't have in-laws, but I'm out of metaphors - it's inertia, it's formidable, and you hate hearing about it. Nobody deliberately wants people to struggle to succeed, but we often don't realize how much we're inadvertently doing just that.
I'm here to tell you that it doesn't need to be this way, and the best way that I can convince you is to talk about pain points that you probably have, and how through making documentation continuous just like your code you can shed guilt by trusting that your docs are always going to be in a relevant and useful state. Hmm, trust - that's a fantastic place to start!
Are you conducting periodic engagement surveys internally? I'd like to strongly recommend that you do, but be extremely thoughtful in how you craft them and involve folks that can help you navigate the many cultures that make up your team. There are fantastic SAAS applications that help you put these together responsibly and effectively.
You should also be paying attention to things like eyes rolling and bad jokes when the documentation is mentioned. While light-hearted, this is how folks that like to avoid confrontation complain about the documentation :)
Don't just ask "Do you trust the documentation?" - ask questions around the periphery instead, e.g. "I am confident that I can find current information and documentation related to my tasks [strongly agree .... strongly disagree]"
Remedy: If docs are continuous, the worst case is a developer seeing the documentation essentially deprecating itself - e.g. an auto-generated admonition saying "This looks to be out of date." This shows that something cares about it, and reduces cognitive load for the developer. This tends to earn trust.
You went through all of the trouble of designing a bunch of abstract classes and interfaces to implement a module subsystem, which you fully expected to be essentially re-used in a bunch of other modular plugin features going forward.
Yeah, that didn't exactly happen, everyone just kinda did their own thing. And that might very well be fine, as long as you're sure that they knew they had the opportunity to just fork the implementation you worked on and make tweaks to suit their own needs. And now your beautiful interfaces are muddled with all kinds of business logic where you really wanted clear separation of concerns.
Remedy: When you make sure that new PRs that lower your documentation coverage kick off issues to assign someone to at least look at it, you catch all kinds of ambiguities. Additionally, when docs are auto-built, always keeping an index of topics where people can discover information becomes simple. Telling your team "just re-use this stuff" breaks in two months from now. Rely on your documentation to tell technical stories.
Do you often answer questions with "well, do you have a minute?" and feel the need to give a short history lesson? And while strange things sometimes happen, have you lost more than 1 or 2 people after just a few months?
Everyone onboarding to your code needs access to the same information that you have about it, and there's a good chance that a significant amount of it is in your head and nowhere else.
When people onboard, they feel pretty vulnerable - there's a lot that they don't know, and they're more reticent to ask questions than they'd be in a more familiar setting. Additionally, some folks have a harder time finding peers and potential mentors than others. Making as much knowledge accessible as possible for self-study means making your team more inclusive.
When confronted with a sense of "just not getting it" - many folks believe themselves to be the culprit, and imposter syndrome can sometimes creep in. But, don't always chalk it off to Imposter Syndrome - others (especially at more senior levels) may recognize this and, well, feel like you didn't really care enough to support them. This is a big problem that people face multiple times in their career, and we can't count on people we haven't hired yet to solve it. It helps to let them know you have a problem and are working on it, but results need to come soon.
Remedy: As trust is gained in the efficacy of the documentation, people will develop a culture of wanting to grow and maintain it. This means good kinds of pressure to get that idea you sketched out on a napkin last night into something others can consume, so everyone (from now until years from now) has the same understanding of that thing as you do. They won't feel cut-off or unconsidered when they hear other people talking about it, and they don't need to wait for it all to "hopefully sink in." And, even in times of huge code churn and upheaval, your on-boarding docs will still be useful.
This speaks for itself. Unless your on-call team is made up of people that always understand all of the code for all of your services all of the time (which is possible, I can admit that), response to incidents is going to mean learning under pressure sometimes with a lack of sleep.
Do we really need to talk about how important it is for people to (1) quickly find out what there is to learn about something and (2) quickly dive into what relates to what they're diagnosing?
Modern service catalogs are a big help with this - you can generally figure out where the code lives, and who owns it, but that's not guaranteed to be helpful because people do things like take vacations (those pesky humans!).
Remedy: Documented on-ramps to a code base with well-maintained troubleshooting guides that include up-to-date code snippets will reduce incident response times in many cases, and allow you to better estimate your SLA capabilities.
I don't think there's a fool-proof way to guarantee that institutional knowledge doesn't leave when a long-term contributor departs. This is true for both proprietary software and open source, and open source generally has the advantage with higher (better) bus factors.
If you don't have some sort of strategy in place to off-board that involves revisiting documentation pertaining to the parts of the code where the person was most active, you've probably got a leak. It may very well be small, and it might not adversely affect your team in the long run, but you should be aware that it's there.
I mention it because, in most early-to-mid-stage startups, it's a very big problem.
Remedy: Allow the person you hire to backfill the role to train on the current docs once they're verified as up-to-date. Ask the departing employee to write a short test to see if the person is up-to-speed, and verify that the documentation is sufficient to pass it. You can not, and will not accomplish this if the documentation isn't already mostly current - there's just not enough time in the usual two-week notice period.
What did you put in your last batch of home-made Alfredo sauce that was so good? Was it dill, or was that the one where you used that new brand of Parmesan?
You might be able to figure it out, but it would be much better if you wrote it right after you made it, and remembered to talk about tempering the cream and the way you knew to lower the flame and the ..... well, you get it. Everything you write is better if you write it when it's fresh in your head.
Don't get me wrong - you could probably nail that recipe today. And it's going to be delicious. And before the food critics jump in, I know there's no cream in classic Alfredo sauce. But that's not the point, it would have been better if you wrote it sooner. The same goes with code documentation. Write it while you're most passionate about the design and folks might just realize you intend it to be reused.
Remedy: Enforcing the need to document at the CI or pre-commit level ensures that documentation gets written at the optimal time, which increases the quality. How you enforce that (blocking the PR or opening an issue with a deadline) is up to you. What matters is that you do it.
How many cool-down cycles are spent catching up on documentation instead of letting engineers work on what they want to work on? That's no fun. Stop doing that. Cool down cycles are for refactoring or fun R&D things, which should also (in an ideal world) not create an additional disproportionate documentation burden.
Remedy: Make documentation continuous so that you don't have to keep spending sprints and cool-down cycles to fix it. Once you have that, you can play with neat things that can keep symbols and paths and stuff current in the docs, or at least automates most of the find/replace overhead.
I could go on here, but that's already quite a bit. Disclaimer: I work for Swimm; we make documentation tools and our CTO wrote the linked manifesto - but we're not talking about this problem in product terms, we're talking about the concepts needed for a solution. How you fix this needs to feel good for you, we don't make the only tools on the market. I only mention it for transparency.
As more and more larger companies modernize and begin to embrace the benefits of micro-services, it's imperative that we level up our documentation strategy. We must be deliberate about getting everything written down and cataloged so new developers can see the entirety of what they need to absorb and pick the paths that work for them.
We must also ensure (by policy) that the knowledge is always relevant and up-to-date. That's how we can remove invisible gatekeepers and really set people up to succeed, while demonstrating that we value them through this effort.