How a private stackoverflow can build team knowledge base one question at a time

Kabir (ko-bir)
May 9 · 5 min read
Photo by Wesley Tingey on Unsplash

In my nearly two decades of experience working with software engineers, the last thing they want to do is document their work! And even if they do, hardly anyone else can use it later. But I found a solution that might just work!

Let’s face it, most average software engineers, don’t like documentation. They love writing new code, hate maintaining old code and God forbid if they are required to write documentation, they would start sharpening their pencils to write a new resume instead! At least this is my experience as a software team manager for the last 18 years. Granted I have not managed the top-tier software engineers that work in Google or Microsoft, so if I am grossly mistaken, please do not read any further.

But this dire statement that I made here is not just based on my personal experience of working with many dozens of software engineers over the years but also based on my network of friends, ex-employees who currently work in all major software and hardware companies in the US.

There are multiple reasons why software engineers suck at documentation. One of them is that most are not people-centric and can’t write documentation for others in mind. Secondly, we know the absolute truth about software documentation:

By the time you write documentation, the damn documentation is out of date!

So why bother right? Well, documentation allows a company to train new hires faster. Most of the time, when a new software engineer joins a company with an existing codebase and operational software, the new hire has to shadow the existing team’s work, learn the stack of software tools and start on non-critical components before they can jump into major threads of the development. In this infancy stage, the new hire is often frustrated as the existing development team might have virtually no quality docs available. And often whatever is available is stale.

So why not make documentation a priority and always have that as part of work products. Small companies and small teams often cannot really see it as a value add for the company, even though it really is! They are so tied up running the ship and driving it forward that pickup up the pieces of the puzzles (code) for someone else to put together with ease is not really a priority.

I have tried everything from internal WIKI, Google Docs, machine-generated documentation from code headers, etc. All eventually failed.

Recently, I found a great solution that we are experimenting with right now and it seems to be working! Ready for the big reveal? Two words:

STACK OVERFLOW

What??? Yes, ask any decent developer and they will tell you that they visit stackoverflow.com on a daily basis for finding solutions to problems already reported and discussed by fellow developers. Stackoverflow has been a critical resource for software development more than any other tool. So what does stackoverflow.com has to do with internal product/service documentation for a company? Three words: Q&A.

Stackoverflow.com offers developers to ask questions and get answers and then the question and answer(s) are up/downvoted by other developers. This process allows the best answer to get the most vote and thus become the likely candidate for the proper solution to the question.

So what if you can create an internal Q&A system using stackoverflow.com for your company’s private development team? You can and you can do it for free for small teams! For the bigger team, you can pay a small fee and they can work with StackOverflow directly like they already do for publically available Q&A.

Now, what is so big deal about this format — Q&A. Imagine this, would you rather read boring 50-page documentation written by some software engineer with hardly any certified writing skills and who probably wrote the damn thing under some form of duress than ask the guy a few questions and get a straight-forward answer from them? Better yet, why not ask the question and get the entire team to put in their two cents worth and learn from all aspects of the issue — development, QA, operations, business, etc. To make this clear, let me show you a Mock exercise below.

Say my company just hired a fresh CS graduate from Cal State, Sacramento. This fellow is new and he was not handed in a bunch of docs to review. Instead, we made him part of our private stackoverflow.com project and told him to review the code and ask questions. So after reviewing some part of the code he posted a question like the one below:

Why do we include tax in the pricing in European countries?

Lead e-commerce developer response:

Because Europeans are smarter than us Americans and like their lives to be simple when they buy products online or hack offline.

Actually, that’s not the technical reason but won’t that have been nice, right? So the technical reason is:

European countries including UK use fixed-rate tax which they call VAT and people are used to seeing the price of a product with VAT included. So what we do is as follows:

Display Price = Price of the Product x 1.{tax rate}

Example, if the price of the product is GBP £100. we will show:

Display Price = £100 * 1.20 = £120. // 20% VAT incldued

Within minutes, the DBA wrote a comment:

Also, since tax rate can change even in Europe, we don’t store the Display Price in the database to avoid recalculation for product information tables. We only store the display price in the transaction tables. So for example, say that a display price of £120 is shown on the only shopping system for a product but internally the database stores:

product price = £120 / 1.20 = £100 so that if the VAT ever changes to say 30% we just simply have to update the central configuration database that stores country-specific data like tax rate. Makes sense?

Finally, a marketing manager chimed in another comment:

Yes, our understanding of the European tax process has been an advantage in launching dozens of franchises in the last few years. Our system handles wholesale price, product price, display price beautifully for both the end-users and our franchise partners. This is a key selling point for us so make sure you have a great understanding of the European/UK tax calculation, which differs greatly from our North American countries.

As you can see, the Q&A allowed folks that normally won’t participate in technical conversation or documentation. All these gems of Q&A are tagged and searchable within the private space of Stackoverflow.com!

So we decided to go with the Q&A model for documentation. On top of this, we discovered that Stackoverflow.com offered the Badge feature for even the private, the free tier of their product. This meant that our teams can not have a friendly competition of asking questions, getting up/downvoted, and getting badges!

In fact, currently, I hold the “TEACHER” badge, which I am very proud of! I strongly recommend that if you have a small tech team and want to check out stackoverflow.com’s private team solution. You can check it out here:

https://stackoverflow.com/teams/create/free

EVOKNOW

EVOKNOW is a multinational e-commerce service provider and…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store