Do you document engineering flows or decisions?

Question

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?

Stas Voronov · Accepted Answer

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

Aaditya Deshmukh · Answer

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.

Tanmay Naik · Answer

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.

ballguy · Answer

It's possible that when we look back at the code or that specific execution, we won't remember the reasoning behind it. According to octordle what I've read, one of the best ways to deal with this is through meticulous documentation.

Daniel Bruce · Answer

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.

Archie Sims · Answer

Documenting engineering flows and decisions is definitely a smart practice! It helps teams understand past choices and trade-offs, making future adjustments easier. Using detailed documentation avoids confusion and ensures consistency. If you're ever considering turning these processes into a guide or resource, book publishers services can assist in organizing and publishing your insights. How do you currently track your decisions?

Cara (Borenstein) Marin · Answer

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...

Abbie Hurst · Answer

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.

Do you document engineering flows or decisions?

Replies