As a developer, we always underestimate the power of the documentation. We (developers) always underestimate the power of the documentation. As a result, we focus more on the code than thinking about the documentation.
Moving to the EM role, I learned the importance of documentation. I have seen that this is one of the many things which differentiate a process-oriented team/work/company from a chaos-oriented one.
Documentation required 10-20% time effort, but the impact or use of it is big or immense
Eg: how many times does a new member join the team and you end up repeating the same things - product, code, process, setting up system & code?. If you document all this, then you can save time as well as this would come in handy every time any developer, product, a person requires a quick overview of your code-bases
Another example is how often the developers move around and you end up asking - "Oh!! the developer who wrote the code has left and we are not sure why we took this approach".
❓❓ I can keep going on and on with an example. But this blog is about what to document?
📝 What to document?
It is common to be unclear about what to document. Well as a developer you can document:
1. Feature and approaches
You can start documenting the approaches, LLD, HLD of the solution of the feature. You can add:
- different solutions
- prefer a solution with reasons
- detailed design of the solution
- dependencies
- APIs contracts
- any trade-offs
- LLD (Low-Level Design)
- HLD (High-Level Design)
2. Knowledge sharing
This is one of the most underrated at work. Document the knowledge sharing. It could have:
- Early review of any tech
- Anything you learned
- A bug you fixed
- A feature we should have
- A complex feature
👉 knowledge-sharing-template.md
3. Code guidelines
If you are a lead, Senior developer, or Engineering Manager then this is 1st documentation you should have.
Code guidelines are helpful for the new devs joining the team, set a bar, and most important reduce the code-review comments (logical comments will stay). After a few revisions, you will see the value in this documentation. We can automate the code guidelines in the project by using CI/CD, linters, and npm packages will help you in automating quite a few things.
4. Checklist
One constant thing in every project (small/big) is missing something while doing the code deployment. I would say it is a must to have a checklist of the things to take care of before doing deployment or going Live.
5. API Contracts
One of the common ways of working is in collaboration with the APIs. Though it is expected that the API team must be documenting their contracts if they are not then you should suggest them to do. Eg: Stripe, PayPal
This should happen from Day-0. Again, the outline would be just like a developer conversation:
- Problem
- Suggestions
- Solutions pros & cons
- trade-offs
- challenges
- feedback
6. Dependencies
While working on the big/large-scale projects or any size of the project it is common to have dependencies on the different teams, code such as APIs, attribute(s), backend, DevOps, etc. I would say it is MUST document the dependencies of your code-base and project.
Your future self and your team will be thankful to you 😊
As an Engineering Manager, allow developers an opportunity to try the different features to know the code-base. The most common problem I have seen is that the new developer is not aware of the code's dependencies. Documentation such as this would be super helpful. Also, This is also an opportunity for developers to push their code to quality by reviewing the dependencies, and if there is something the developer can fix something.
7. Sprint Milestones, celebrations, retrospect, and reviews
As a senior developer, tech lead, or Engineering manager block time in your team and at the end of your sprint present sprint milestones, review, and celebrate. Yes, we do have JIRA, yes, we do have the scrum but as a developer doing a playback (playback of the work done in the last sprint) is important.
Why? it is an opportunity to appreciate the good work, celebrate the milestones, and reflect back on mistakes and retrospect.
This document could be a reference when a team wants to see how far we have come, what we have delivered, and milestones achieved.
8. Cookbooks
A cookbook is a beautiful way to set the standard guidelines across organizations from the engineering side. For example, a cookbook could have the performance guide, metrics, measurement of front-end apps, back-end, API.
A cookbook is a 'black book' for your developers to see the area to focus on, what is expected, how to achieve, etc.
As a tech lead or engineering manager , investing time in the Cook Book is a good investment. The cookbook helps the developers what is expected from their contribution to the product/project, how the review of their work will be done or how would be measure. Eg: Accessibility should be at least AA level. If a developer's code is meeting that then it is a concern. Similarly, these cookbooks would help in quantifying the quality of the code.
9. Brag Document
A brag document is a personal document that every developer should maintain. This document will have all the things you have achieved - small/big. Basically, everything which created an impact - code, tech discussion, mentoring, hiring, tech talk, etc.
At the time of your yearly review, you can refer to this document to look back at your progress, share with your leads, or whenever you feel low you can just go through this doc to reflect back.
9. Project Starter Guide
Create a project starter guide for your project. This document will reduce the repetitive work/meetings/communication. This document could covers:
- Summary of your project
- Team structure
- Product/Project walkthrough
- WOW (way of working)
- Code walkthrough
- Tools and Applications required
- Escalation Process
- and anything which is required in your project
- HLD (High-Level Design)
📇 Where to document?
- Wiki (GitHub)
- confluences (Atlassian)
- Drive (any Google, One Drive)
- or a shared folder with readme(s), or doc(s)
🔄 Is it a one-time effort?
Well, a few documents would be just a 1-time effort but a lot of the documentation needs to be updated from time to time as you will move ahead or your project.
How to make it automated? Well, fortunately, a few things can't be automated. Yes, I said, fortunately...The reason is: a lot of documents depend on the developer's experience. No harm in doing the manual effort. But there are a few tools that can be used - JSDocs
Thank you @iamshadmirza, @nchiarora, @rahulrana_95,@prasadsunny1,@PKodmad,@izshreyansh for reviewing and providing valuable feedback.
Happy Learning!!
Top comments (0)