How to write wiki type documents effectively?
Background:
Being pressured to deliver at high speed all the time, my team doesn't seem to value wiki type documentation a lot.
When starting a project/feature, we often have a high level design doc & design meeting to talk about high level infrastructure, and we make key trade-off decisions together as a team. If we are lucky, we get another low level design doc & meeting focused on sequencing of actions & interaction between class level objects.
We rarely seem to go back to our initial design doc after initial design phase of a project to update them and explain the actual final product we built and maybe some additional design decisions we made during implementation.
As a result, documentations are kind of dead after facilitating the initial design review. For legacy projects, high quality docs are extremely hard to come by and most just rely on reading large amount of code to understand how things work (nothing wrong with this but I think high quality documentation can save lots of time here).
I understand we don't want to boil the ocean and write everything in painstaking details, but we should at least have enough to help people understand responsibility of services and contract between them.
Questions:
- Could you share your view on this topic and how you find your balance?
- Do you believe it's always worth it to go back to documenting after finishing a project/feature and update it as if you are explaining it to someone new to the team/project?
- Could you share any resources we might already have on this topic as well?
Discussion
(3 comments)- 44 months agoSenior Software Engineer @ Nvidia
From my experience, we can take every stage of implementation as an opportunity for documentation.
-
When you write code, adding good class, function level documentation string, adding dev notes to breakdown complex logic works as a great means. Using meaningful names for classes, functions etc will also help other engineers / the future go through the code quickly.
-
The next step is, when you’re going to submit your merge request, this can be used to capture few more important details. I use the following framework in all my MRs:
- Changes Description:
- Testing strategy:
- document details about manual / automated testing (unit/integration/e2e)
- Commands run:
- Evidence of changes:
- failures / exceptions raised
- edge cases
- successful / green path cases
-
Finally, in order to capture the larger decisions like framework choices, schema design etc, I would recommend to create a Wiki page / Confluence page before you start working on the code. Update the page as you conclude your analysis. This way, the research is done and you’ll capture it on the way instead of separately taking time to create the wiki (as you mentioned speed is critical in your project).
-
- 24 months agoMid-Level Software Engineer [SDE 2] [OP]Amazon
Thank you curious-soul! I especially enjoyed your insight about blending wiki writing into part of regular development cycle instead of a separate phase after development is done. That's very helpful 👍
- 24 months agoTech Lead/Manager at Meta, Pinterest, Kosei
In my experience, one helpful way to frame this is around the impact of the documentation for onboarding a new engineer.
If a new engineer finds the design doc helpful, it's worth following through and documenting. Remember: new hires are overloaded with tons of info. So if you can argue that future engineers will rely on the documentation, your teammates should also be convinced of its value.
This also gives you a concrete person who you're writing for. You're not updating wikis for the sake of updating wikis.
