Seems like "yet another tool to try to offset the problem of requirements, code, and architectural decisions not being adequately documented for future staff to understand." Sometimes I wonder if software teams should add technical writers embed with developers, architects, QA, and BA assets to actually document All The Things and keep documentation up to date. Yes, that will mean re-writing documentations as people change their minds in response to business needs but it would provide an historical record that answers "How the hell did our systems end up looking like this?" which seems to plague every organization that hires programmers to write custom code. Sometimes it's hard to give the developers who wrote the code the benefit of the doubt that they made the wisest decision based on all known variables at the time. I'm certainly guilty of questioning the intelligence, breeding, motivations, etc of the programmer of an app I had to modify once... only to realize that I had written the code in question four years previously. Eventually I remembered why the feature had to be coded that way and wrote a 1200 word comment section explaining why the feature was written the way it was and how one should orient their state of mind to understand and edit the logic. And I further apologized for the clusterfuck of code that the feature was and left my personal email address in case a future programmer wanted to berate me for it. And three years later I did get an email from someone saying they had been laughing for ten minutes because they had gone from "WTF?" to gradual understanding as they read through my verbose description of why... ending with laughter that I was willing to take whatever vitriol they had left over via email so they could vent and get back to work. Whether that dev updated the comments to reflect their changes is something to which I have no answer.
For the past few weeks, I've been digging into a codebase that is legendary among my team for its complexity. While I have disagreements over some architectural choices, the biggest pain point has been the lack of documentation: when I look up the JIRA story referenced in the git commit, it's often a 4-pointer (the highest value we use before we break stories up) with no context. I found one story that had EIGHT pull requests linked to it, and all that was documented was "modify {entity}".
This code base is not even two years old, and I'm already concerned about its long-term viability. The colleagues that worked on it are extremely helpful, but details are fading from their memories over time. Its one saving grace is the fairly extensive test suite, so at least I have some degree of confidence that I won't be breaking things whenever I look at it the wrong way.
> Sometimes I wonder if software teams should add technical writers...
I have been wondering the same thing fairly frequently of late. I see a few different potential benefits to something like this:
1) I communicate with relatively low friction face-to-face, but writing is like pulling teeth. Being able to outsource the formalization of knowledge would allow me to spend my time doing what I'm good at. I would hazard a guess that I am not alone in this matter.
2) There have been numerous times in the past when, despite my best efforts, some key subtlety of code that I had written was not communicated effectively until someone essentially comsumed my communications and regurgitated their own understanding of it. Having this process be the default would yield documentation that was a lot more effective at educating rather than simply being a reference to those that already know.
3) There is a surprising segment of developers that do not value clarity over volume, and most interactions with non-trivial quantities of their code result in having to engage in what is essentially a guided re-write. Having every long-term artifcat subject to a professional bringer-of-clarity would significantly reduce friction in the medium, allowing for much bolder and more effective trade-offs when reconciling a new requirement to an existing system.
4) Having well-archived, clear documentation would significantly increase the speed at which new members become effective, while also lowering the overhead imposed on existing team members.
I think in most cases "perfect" documentation that is always up to date, fully covers the software project, etc. would be overkill. Most of us aren't writing software for self-driving cars, rocket ships, and surgery suites. We're writing "spreadsheets in the cloud" where requirements change on every conference call, and documentation is JIT because that's all the client can afford.
Private Q&A like this from Stackoverflow would be perfect for my team. It would boost our institutional memory so that when questions are asked they're stored in SO, searchable, maintainable, etc. instead of stored in a Slack archive.
Pushing the need for clear documentation is a battle I find myself frequently fighting. Many devs just aren't sure how to prioritize it or write it, and even worse, many seem to have absorbed the idea that code should be self documenting and that comments are a code smell.
Whoever is responsible for the idea that comments are code smell deserves to receive all future vitriolic emails from anyone who ever stumbles into a complex nest of undocumented code and has to figure out what the hell they're looking at.
There's nothing like writing up an Evernote or Wiki article on some feature, process, or how/why something works... and then nobody on the team ever reading.
I love writing documentation from time to time. But this helps by getting you to write documentation for only things people are asking about.
SO is bad with search, entirely giving it away for Google to find relevant answers. In a wiki, at least I can follow the structure to find relevant pages, but in the heap of badly phrased questions it will be a pain to find anything relevant.
I love writing documentation too, but from years participating on Stack Overflow I found it most unreliable for the purpose. As I once quipped, "Imagine Wikipedia where there are several hundred articles on the New York city. And one that Google links first is copy-pasted from Encyclopedia Britannica, 1913. And every single day several kids from elementary school start a new one."
SO is torn between essentially ambiguous goals, providing fast on-site answers and being a reusable knowledge base. And it's good with the latter only because of Google. Without Google it will be no better than fast on-site answers on Slack.
I think the win would be in making the answers more findable. Confluence is great for writing documents and laying out pages in a hierarchy, but full-text search is still very hit and miss. Especially when you have 50 projects that all have the same keywords and 49 of them are irrelevant.
"Documentation on-demand" seems a great solution indeed!
Although $5/month per user is not cheap. I work at a medium-sized funded startup and I doubt it would be approved for overall use (as it would be nice to include other teams as well, like Marketing, Analytics, Customer Support).
It is the same price of GSuite, that adds a ton more value than SO for Teams could ever add.
This is where the rule of threes is useful for me. The third time I find myself answering the same question for someone, I'll make sure it get put in the wiki. Then next time I get asked, I just give the asker the URL.
Saves time and breath. Also serves as a mini-tutorial on the utility of the wiki.
Over the years I’ve concluded, reluctantly, that the ONLY documentation solutions that matter are the code, revision control logs and issue trackers.
Create massive comment blocks to explain things if you have to but put it all there in the code, next to the things that matter. Then it has half a chance of still being accurate. And, you know exactly where the documentation is. If the code becomes obsolete and is removed, you naturally strip out documentation that is no longer relevant at the same time.
Revision control log messages are important. I so hate lazy messages; if you change 5 files in random ways and your message is “fixed bug”, I think you should be fired. If it’s in the issue tracker, your log had better mention the number. Add a paragraph daring to explain what the hell you did so I can read a sensible log history and figure out what happened when.
Issue trackers are useful for capturing every relevant detail, especially new information that is found while the bug is being investigated. The bug might come up again, and details can help to sort it out.
You are assuming this is a tool for developers. It can be for anyone organized as a team, or based around a product.
A product for example has sales, marketing, support, development, and more. They could all coexist in a single stack centered around the product for example.
The conclusion I've come to in regards to comments is that each function should have a comment about WHY it is needed. As you said the code will change and exactly what it does will morph, but the why describes the architecture (somewhat) and hints at the abstraction model.
I'm excited at the potential this has to organize your own internal information that normally lies stagnant on a wiki (or heaven forbid, email) with no context of whether it's still valid or useful to anyone. It seems like it would be particularly useful for organizations with a distributed work force.
On the other hand, so much of StackOverflow's value comes from the economies of scale at hand, and I'm uncertain how well the model scales down to small sized teams or even medium sized companies.
There was an open source version of Stack Overflow that I set up internally a few years ago at a previous company. I was the only one on the team who actively used it, but even then I found it useful as it was a place to squirrel away these useful little pieces of information you come across and don't know quite what to do with. I ended up coming back to find stuff I'd put there a few times and was starting to refer others to questions here and there.
Then after a couple months, just as it felt like it was getting some traction, the server got wiped out accidentally by our server team and there were no backups. I never got around to putting it back up.
I hope not having your knowledge base arbitrarily wiped out by careless admins would be a feature of this service.
yeah, that's definitely a huge product challenge for us!
some things do work differently than stackoverflow.com to help with that - we built integrations to help surface questions to the right people in your team quickly (rather than the shotgun approach on the public site). and we've also built mechanisms to help guide you towards building a successful community (since it starts as a blank slate).
So the biggest reason why I can see this succeeding is because of onboarding. In fact, I'd say that's the killer feature. It takes one person going through a development environment setup process to be really useful. They'll ask a lot of questions, get the answers...and then the setup process is suddenly really well documented without anyone having to go through the trouble of documenting it without knowing what to document.
Since new employees are expected to ask questions on how to get things working, using SO for Teams is natural. Then, explanations that would normally be sent in pieces over IM can be recorded.
The information still ages, but aged information on the right track is infinitely better than nothing at all.
My question is, is this better than your self-hosted wiki? At least that's cheaper and isn't a vendor lock-in. Sure wiki doesn't have the best possible UI and the UX might be too so-and-so. If I were in a position to buy this kind of service I'd still want something more out of it.
Maybe if it offered a way to export Slack threads into SO as questions so they wouldn't get lost. Sure you could generate those questions manually from the thread and maybe prune them a little but I've found mostly people are too lazy for extra-work like that. Anyway that's my first impression, take it as you want.
If your goal is to post problems and associated solutions, yes it is better than a Wiki.
First, it gives you a template to post in - you are not given a blank page and told "document this"
Second, it encourages you to document single, smaller, focused pieces of information. You're not being asked or expected to write a multipage document, you're being asked to write a single entry in what essentially is a crowd sourced FAQ.
One thing the SO approach also does is that it respects the content that each person posts. If I post an answer, only I can modify it. Nobody will modify my answer to reflect what they think, and make it seem as if I was presenting a different solution that what I suggested. What people with alternative ideas CAN do though is post alternative answers, or comment on my answer with suggested changes.
Nearly every company I've worked at is already paying for a vendor locked-in wiki. Of course, ADDING StackOverflow means they're now paying for TWO vendor locked-in wikis (at least until they can shut down the old one, if ever), but it may be still be a net improvement.
Has there ever been a self-hosted wiki that was good? I'm only half joking - we've been through a few of them, and never found anything that was easy enough to use that people actually would. And thus everything gets shoved into email, and perpetually lost.
I'm actually kind of excited about the idea of an internal StackOverflow. Of course, people would have to actually use it, and that battlefield is littered with the shattered corpses of a million productivity and communication and social tools.
Stack Overflow largely relies on Google Search, but for private teams it won't be available. And internal search is just unreliable.
Also I fail to see how answers on SO for Teams are supposed to be less "stale" than your old wiki articles.
For me, at least our corporate wiki is more organized, without duplicates, whereas Stack Overflow's modus operandi is largely relies on creating thousands of duplicated questions.
Actually this brings up one of the things I like the most about this SO for Teams idea - it could also be used as a sort of slant.co substitute, where a large dev team is trying to settle on a common programming language or persistence framework, and each person can register their opinion or vote on an existing one.
After N days, the whole group decides to select the option with the most votes. Since voting is anonymous, everyone can give their honest opinion, or even vote for multiple.
If you don't like the "opinion-based" close reason, you can just not use it on your team.
I'm sure I'm ignorant of other reasonable options, but this one is quite appealing as a small co, even if only used by one person. Just yesterday I was thinking about better ways to store easy-to-find answers to those dang tech issues that pop up once every six months. "How do I install pip manually on OS X with xyz constraints?"
Sorry for the confusion. Your assumption is correct. $10 month total for the first 10 users (so, regardless of whether you have 3 users or 9 users, it's still $10/month). And then $5 per new user after that.
Slightly offtopic, I recently looked at all top free internet websites/services that I use and wondered which of them I would miss if advertising dollars dry up. For me, it turned out to be stackoverflow and Google. I truly hope stackoverflow is a profitable venture at this point. I hope they have been trying various avenues to make money but no o no one has any info on profitability. Job ads pay well, but there is fierce competition there.
What did you have in place before this (wiki, Slack, Yammer or something like it) if anything?
Is this better than finding the right person to ask, or posting in slack or something?
In my org we have a wiki on topics and if that fails an "experts" list with people to contact for further help. There is also a yammer group for asking questions, but that is rarely used. I think this could be helpful, but whether or not it's worth the cost would be a question for someone else.
I have thought about building this so many times. I think there is a need for it, particularly for non-technical teams where processes don't evolve that fast, but adoption will be hard to ignite.
This is an interesting play but doesn't seem like a good fit.
The examples on the front page: "how do I connect to our database", "what kind of email templates do we have". Are these questions that you're going to get multiple answers for and I'm going to upvote the best and/or select one as the "selected" answer. I would think this would be a sign of dysfunction in most cases. And how does the gamification play into it? (maybe it's a secret bus-factor detector.)
It seems like a regular wiki/knowledge base would be a better fit for this kind of knowledge. How would the SO structure help.
A related note, I wonder if you can disable the "Soup Nazis"[1] feature or it's too deeply embedded in the psyche of the product.
[+] [-] parvenu74|7 years ago|reply
[+] [-] organsnyder|7 years ago|reply
This code base is not even two years old, and I'm already concerned about its long-term viability. The colleagues that worked on it are extremely helpful, but details are fading from their memories over time. Its one saving grace is the fairly extensive test suite, so at least I have some degree of confidence that I won't be breaking things whenever I look at it the wrong way.
[+] [-] ShroudedNight|7 years ago|reply
I have been wondering the same thing fairly frequently of late. I see a few different potential benefits to something like this:
1) I communicate with relatively low friction face-to-face, but writing is like pulling teeth. Being able to outsource the formalization of knowledge would allow me to spend my time doing what I'm good at. I would hazard a guess that I am not alone in this matter.
2) There have been numerous times in the past when, despite my best efforts, some key subtlety of code that I had written was not communicated effectively until someone essentially comsumed my communications and regurgitated their own understanding of it. Having this process be the default would yield documentation that was a lot more effective at educating rather than simply being a reference to those that already know.
3) There is a surprising segment of developers that do not value clarity over volume, and most interactions with non-trivial quantities of their code result in having to engage in what is essentially a guided re-write. Having every long-term artifcat subject to a professional bringer-of-clarity would significantly reduce friction in the medium, allowing for much bolder and more effective trade-offs when reconciling a new requirement to an existing system.
4) Having well-archived, clear documentation would significantly increase the speed at which new members become effective, while also lowering the overhead imposed on existing team members.
[+] [-] heartbreak|7 years ago|reply
Private Q&A like this from Stackoverflow would be perfect for my team. It would boost our institutional memory so that when questions are asked they're stored in SO, searchable, maintainable, etc. instead of stored in a Slack archive.
[+] [-] dbingham|7 years ago|reply
Whoever is responsible for the idea that comments are code smell deserves to receive all future vitriolic emails from anyone who ever stumbles into a complex nest of undocumented code and has to figure out what the hell they're looking at.
[+] [-] abhishekjha|7 years ago|reply
Version control?
[+] [-] kamaal|7 years ago|reply
Part of CMM level 5 process was things like 'Knowledge teams' which did exactly that.
Agile eat CMM for lunch though.
[+] [-] bluedino|7 years ago|reply
I love writing documentation from time to time. But this helps by getting you to write documentation for only things people are asking about.
[+] [-] colshrapnel|7 years ago|reply
I love writing documentation too, but from years participating on Stack Overflow I found it most unreliable for the purpose. As I once quipped, "Imagine Wikipedia where there are several hundred articles on the New York city. And one that Google links first is copy-pasted from Encyclopedia Britannica, 1913. And every single day several kids from elementary school start a new one."
SO is torn between essentially ambiguous goals, providing fast on-site answers and being a reusable knowledge base. And it's good with the latter only because of Google. Without Google it will be no better than fast on-site answers on Slack.
[+] [-] tootie|7 years ago|reply
[+] [-] soneca|7 years ago|reply
Although $5/month per user is not cheap. I work at a medium-sized funded startup and I doubt it would be approved for overall use (as it would be nice to include other teams as well, like Marketing, Analytics, Customer Support).
It is the same price of GSuite, that adds a ton more value than SO for Teams could ever add.
[+] [-] klenwell|7 years ago|reply
Saves time and breath. Also serves as a mini-tutorial on the utility of the wiki.
[+] [-] some_account|7 years ago|reply
[+] [-] makecheck|7 years ago|reply
Create massive comment blocks to explain things if you have to but put it all there in the code, next to the things that matter. Then it has half a chance of still being accurate. And, you know exactly where the documentation is. If the code becomes obsolete and is removed, you naturally strip out documentation that is no longer relevant at the same time.
Revision control log messages are important. I so hate lazy messages; if you change 5 files in random ways and your message is “fixed bug”, I think you should be fired. If it’s in the issue tracker, your log had better mention the number. Add a paragraph daring to explain what the hell you did so I can read a sensible log history and figure out what happened when.
Issue trackers are useful for capturing every relevant detail, especially new information that is found while the bug is being investigated. The bug might come up again, and details can help to sort it out.
[+] [-] pugworthy|7 years ago|reply
A product for example has sales, marketing, support, development, and more. They could all coexist in a single stack centered around the product for example.
[+] [-] sametmax|7 years ago|reply
Because an API reference is a very poor doc.
[+] [-] matt4077|7 years ago|reply
I also doubt that anyone could efficiently learn, say, CSS just by reading the Firefox source, revision history, and bugzilla.
[+] [-] snarf21|7 years ago|reply
[+] [-] unknown|7 years ago|reply
[deleted]
[+] [-] coryfklein|7 years ago|reply
On the other hand, so much of StackOverflow's value comes from the economies of scale at hand, and I'm uncertain how well the model scales down to small sized teams or even medium sized companies.
[+] [-] klenwell|7 years ago|reply
Then after a couple months, just as it felt like it was getting some traction, the server got wiped out accidentally by our server team and there were no backups. I never got around to putting it back up.
I hope not having your knowledge base arbitrarily wiped out by careless admins would be a feature of this service.
[+] [-] cheath|7 years ago|reply
some things do work differently than stackoverflow.com to help with that - we built integrations to help surface questions to the right people in your team quickly (rather than the shotgun approach on the public site). and we've also built mechanisms to help guide you towards building a successful community (since it starts as a blank slate).
[+] [-] Shank|7 years ago|reply
Since new employees are expected to ask questions on how to get things working, using SO for Teams is natural. Then, explanations that would normally be sent in pieces over IM can be recorded.
The information still ages, but aged information on the right track is infinitely better than nothing at all.
[+] [-] cryptos|7 years ago|reply
[+] [-] tekkk|7 years ago|reply
Maybe if it offered a way to export Slack threads into SO as questions so they wouldn't get lost. Sure you could generate those questions manually from the thread and maybe prune them a little but I've found mostly people are too lazy for extra-work like that. Anyway that's my first impression, take it as you want.
[+] [-] pugworthy|7 years ago|reply
First, it gives you a template to post in - you are not given a blank page and told "document this"
Second, it encourages you to document single, smaller, focused pieces of information. You're not being asked or expected to write a multipage document, you're being asked to write a single entry in what essentially is a crowd sourced FAQ.
One thing the SO approach also does is that it respects the content that each person posts. If I post an answer, only I can modify it. Nobody will modify my answer to reflect what they think, and make it seem as if I was presenting a different solution that what I suggested. What people with alternative ideas CAN do though is post alternative answers, or comment on my answer with suggested changes.
[+] [-] willcole|7 years ago|reply
[+] [-] coryfklein|7 years ago|reply
[+] [-] megaman22|7 years ago|reply
I'm actually kind of excited about the idea of an internal StackOverflow. Of course, people would have to actually use it, and that battlefield is littered with the shattered corpses of a million productivity and communication and social tools.
[+] [-] colshrapnel|7 years ago|reply
Also I fail to see how answers on SO for Teams are supposed to be less "stale" than your old wiki articles.
For me, at least our corporate wiki is more organized, without duplicates, whereas Stack Overflow's modus operandi is largely relies on creating thousands of duplicated questions.
[+] [-] vortico|7 years ago|reply
[+] [-] baud147258|7 years ago|reply
[+] [-] coryfklein|7 years ago|reply
After N days, the whole group decides to select the option with the most votes. Since voting is anonymous, everyone can give their honest opinion, or even vote for multiple.
If you don't like the "opinion-based" close reason, you can just not use it on your team.
[+] [-] KyleBrandt|7 years ago|reply
[+] [-] gchp|7 years ago|reply
It's built on Django, and covers all of the standard Q&A features that I've needed to use.
[+] [-] baud147258|7 years ago|reply
https://www.joelonsoftware.com/2018/05/03/announcing-stack-o...
It was already linked on HN:
https://news.ycombinator.com/item?id=16985574
[+] [-] Clanan|7 years ago|reply
[+] [-] shusson|7 years ago|reply
[+] [-] cheath|7 years ago|reply
[+] [-] unknown|7 years ago|reply
[deleted]
[+] [-] coryfklein|7 years ago|reply
[+] [-] sdsdsdsdsdsds|7 years ago|reply
[+] [-] rwilsonperkin|7 years ago|reply
[+] [-] nwsm|7 years ago|reply
Is this better than finding the right person to ask, or posting in slack or something?
In my org we have a wiki on topics and if that fails an "experts" list with people to contact for further help. There is also a yammer group for asking questions, but that is rarely used. I think this could be helpful, but whether or not it's worth the cost would be a question for someone else.
[+] [-] Someone1234|7 years ago|reply
[+] [-] cryptos|7 years ago|reply
[+] [-] nkg|7 years ago|reply
[+] [-] yehosef|7 years ago|reply
The examples on the front page: "how do I connect to our database", "what kind of email templates do we have". Are these questions that you're going to get multiple answers for and I'm going to upvote the best and/or select one as the "selected" answer. I would think this would be a sign of dysfunction in most cases. And how does the gamification play into it? (maybe it's a secret bus-factor detector.)
It seems like a regular wiki/knowledge base would be a better fit for this kind of knowledge. How would the SO structure help.
A related note, I wonder if you can disable the "Soup Nazis"[1] feature or it's too deeply embedded in the psyche of the product.
[1]https://www.embeddedrelated.com/showarticle/741.php
[+] [-] amelius|7 years ago|reply