As a software team manager for over 21 years, I've learned that most engineers dislike documenting their work. They love coding new features but hate maintaining old code or writing documentation. While this may not apply to top engineers at big tech firms, it rings true for most average developers. This aversion to documentation stems from several reasons. First, engineers tend to be less people-centric and need help to write docs with others in mind. Also, documentation invariably becomes outdated quickly, so why bother?
However, good documentation brings immense value. It allows companies to train new hires faster. When new engineers join, they must shadow existing work, learn the tools, and start on non-critical items before tackling significant projects. Without quality documentation, new hires become frustrated, spending excessive time getting up to speed.
I've tried various solutions - internal wikis, Google Docs, auto-generated docs from code - but all failed eventually. However, I recently discovered a great approach: Private Stack Overflow.
Leveraging Stack Overflow's Q&A Format
Every good developer visits Stack Overflow daily to find solutions fellow coders discuss. It has become an indispensable resource.
Stack Overflow's core strength lies in its Q&A format. Developers can post questions and get answers, which get upvoted/downvoted by the community. This surfaces the best solutions organically. What if we create an internal Q&A system on Stack Overflow for our private team? We can, and it's free for small teams!
With a private Stack Overflow instance, asking questions and getting targeted answers from colleagues beats reading lengthy theoretical documents. The team collectively contributes knowledge through focused Q&A, benefiting from diverse perspectives - engineering, QA, ops, business, etc.
A Mock Example
Say my company hired a new CS grad who wasn't handed any docs. Instead, we added him to our private Stack Overflow and told him to review the code and ask questions.
After inspecting some code, he posted:
Why do we include tax in pricing for European countries?The lead developer responded:
European countries use fixed VAT rates, so people expect prices listed with tax included. We do:
Display Price = Price of Product x (1 + tax rate)
E.g., if product costs £100 and VAT is 20%:
Display Price = £100 * 1.20 = £120
The DBA added:
We don't store Display Price in the database since tax rates can change. We only keep it for transactions. This avoids recalculating product prices if VAT changes later.
E.g., if Display Price is £120 but the database stores:
Product Price = £100
If VAT increases to 30% later, we will update the tax rate config.
And the marketing manager commented:
Handling European taxes properly has helped us launch dozens of franchises successfully. Make sure you understand the EU tax calculations.
This example demonstrates how Q&A draws knowledge from all roles, not just developers. The conversations are tagged and searchable, too!
Additional Benefits
Stack Overflow also provides badges and gamification features, even for free private instances. Our team now has a friendly competition, asking and answering questions and earning badges!
If you lead a small engineering team, I recommend exploring Stack Overflow's free private offering. It has worked remarkably well for us as an engaging team knowledge base.
Check it out here:
https://stackoverflow.com/teams/create/free
Reference:
Original post appeared on medium.com