This post should be as short as “For a tech lead, time committed to working on documentation is time taken away from their immediate role”. Let’s break down that claim. Who is responsible for a software project’s documentation? There are a few possible stakeholders when it comes to documentation: Developers Senior developers Tech leads Product owners Project managers Developers have self-documenting code. Product Owners and Project Managers do not work with code on a daily basis so they often cannot create documentation. Many times the task of writing documentation falls on : Tech Lead Senior Software Developer Primarily because they know the value of having at least some documentation. Sometimes, it’s a business requirement that they are responsible for. Possibly also, because they have to answer lots of questions on a daily basis and they operate as walking knowledge bases. Instead of answering the same question multiple times, they can say Read The Fucking Manual (RTFM) but they need to have a Fucking Manual (FM) to say that. What happens when Tech Leads write documentation? In the case where tech leads or senior developers decide to write documentation, the issue of keeping the documentation still arises. up to date They need to answer the question because, without a clear answer, developers think . “what if the code changes?” “why should I write documentation if it could be outdated tomorrow?” Tech Leads cannot make demands without outlining tools and reasonable processes. Developers' time is too expensive to be spent on excessive documentation maintenance, caused by incorrect tooling. Problem: Tech Leads need to have some documentation. Tech Leads cannot spend a lot of time writing documentation. Developers can write documentation in a distributed way but they need to be sure that their time is not being wasted. Current solutions for Tech Leads: Don’t write documentation at all, answer questions on a daily basis. This solution will work to some extent! Especially in small companies where you do not have so many stakeholders. Auto-generate documentation from code. Only good for API-like documentation but will not work for business/product documentation. The solution: Having a system that links documentation with code This for me seems sounds like a viable solution. The way it works is in scenarios where you have documentation that changes once the codebase changes, you link the documentation with the code. This allows for automatic updates to the documentation that reflect changes made to the code. For example, once a filename is changed or if a linked method/class is moved in the file, the links are updated automatically as well. You can either create software for this on your own or use existing software on the market. Conclusion No one will blame you for having no or limited documentation. The same was common 20 years ago with tests. No one blamed you for having no or limited tests - because every team wrote good code which didn’t have bugs so it didn’t have to be tested :) In the same way today, every team writes self-documenting code which everyone can read in order to understand what is inside… ;) Let me know in the comments if I’m missing something and what you think about the idea of linking documentation with code.

Read My Stories

Too Long; Didn't Read

Make resilience your competitive advantage

Beware of Documentation Management. A Techlead's Hell Loop.

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

10 Best JetBrains IDEs Plugins to Boost Your Productivity in 2021

4 Steps to Actually Finish your Side Project

5 Fantastic Developer Tools for Asynchronous Communication 🎯

Supercharge your Software Development Productivity by Using these 5 Tools

9 Fun Command-Line Tools to Make Your Life Easier

10 Best JetBrains IDEs Plugins to Boost Your Productivity in 2021

4 Steps to Actually Finish your Side Project

5 Fantastic Developer Tools for Asynchronous Communication 🎯

Supercharge your Software Development Productivity by Using these 5 Tools

9 Fun Command-Line Tools to Make Your Life Easier

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps