harisrid Tech News

Documents. Documents. Documents. Show me the documents! – some detective you see in a popular crime TV show

Hey all!

I briefly want to go over documentation, and why this matters! I’ve taken my turn across quite a number of big tech organizations, and I’m surprised how little we document. Yeah I get it, documentation feels like flossing your teeth – there’s little technical value to it, because it’s mostly writing. But wait, there is value. There’s value is making is easier for other folks on your team – or across teams – to understand what’s taking place in your code. And there’s value in leaving a cleaner codebase and making it easy for your future maintainers and your future developers to know what they are doing.

But What the Heck Does Good Documentation Even Resemble? And across different levels?

You know it when you see it.

That’s a good question!

Good documentation should be concise but comprehensive. For example, if I’m designing a system, I should be able to create a brief FRD – Functional Requirements Document – which presents a top-level view spanning a couple of sections : background, non-functional requirements, functional requirements.

If I am developing a code in a single microservice, per say, I should be able to open a quick ReadMe.md file explaining the feature – the business reasons for why a feature was built, key high-level methods, test cases, and detailed steps for unit test and end-to-end tests.

At project/platform level, documentation needs less granularity. I need to see a slightly different ReadMe.md file . It should explain the business reasons justifying the project, a list of relevant microservices, a breakdown of data flows and workflows, identified dependencies, and owners/points of contact ( the individuals who develop and maintain the services ).

The Many Benefits!

• Authoritative Source of Truth – if a group of developers lacks consensus on what is a team best practice or a piece of the system, they can reference what’s been historically written and approved.
• Centralization – documentation lends to the pattern of a central source of truth, and it’s easy for other personas to quickly locate pertinent information.
• Expedited onboarding – the better the documentation, the less time a dev spends in onboarding. This ties in with reduced KT session frequency.
• Reduced Knowledge Transfer ( KT ) Session Frequency – Devs don’t have to spend as much time learning tribal knowledge and asking other engineers clarifying questions on how a system operates or how to test a system, if the information is already available in a easy-to-access form.
• Shareability – builds a top centralization. Information can be quickly shared across multiple engineers or personas. We can reduce the number of clicks and web page navigation depth.