Do you document engineering flows or decisions?
Yogini Bende
7 replies
While building a product, we make some decisions that are best suited at the moment. Some of them might have some trade-offs.
When we look back at the code or that particular way of execution, we might not remember why we did it that way. I have been reading that maintaining documentation is an excellent way to deal with this.
Do you maintain such documentation? How do you keep track of these thought processes?
Replies
Stas Voronov@stas_voronov
Good question!
We did huge research about it and building a product to solve that pain actually :)
So, in the end, what teams use:
- Excel spreadsheet
- Notion tables
- Confluence
- Miro
- Nothing, just emails and then they search decisions in email
Just today I built Notion template to track questions and collect decisions (Just enter that discount code 66c7mou):
https://staasvoronov.gumroad.com...
Would be glad to hear any feedback about it
Share
Yes, we maintain documentation of high level decisions.
But not everything is documented when it comes to code. Comments work just fine most of the time, except for some very specific features where we know that extra digging would be needed in the future. This has helped a lot when going back and changing things or fixing bugs caused by new features clashing with old ones.
We kept it as simple as possible:
- User stories documented product decisions and any trade-offs
- Software was covered by automated tests describing the behaviour
- Software was well documented, each class, and function had JSDoc and each micro-service had a README.md describing how to deploy and any "prickly" bits.
Part of my work is to create best practices for projects in my organization, capturing metrics for these best practices, and measuring them accross multiple KPIs. We study tools and practices used in the industry and our organization. The best way to capture such information is to classify them into categories like Traceability, Source Control, CI strategy, CD strategy, Quality etc. We use any collaborative diagramming tool for brainstorming and document it in Confluence. Confluence fits well because the organization is heavily invested in the Atlassian ecosystem Jira, Bitbucket.
One of my favorite records to keep is status dumps. Whenever I switch off of a task, I write where I'm up to and what's next. This makes it easier for me to jump back into different tasks as I'm working.
It also has the side-effect of creating a handy historical log of different decisions and roadblocks I run into.
Have you tried this approach?
https://www.stashpad.com/blog/st...
I think it's important to note that what the specs look like should also depend on who they're written for Wiki expert online, they should look different when they're for your internal team and not an external team.