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.
Perhaps a framework for minimal effective documentation would help. Requiring documentation that starts with "As a {role} I want to {verb}" might not be as effective as saying an application can be defined as a set of features, and each feature is described by it's list of acceptance criteria -- each of which map to one or more unit tests. In addition to all of this would be something in free-form prose from a business operations person describing why a feature needs to be added or modified. "Our competition is kicking our ass because they have feature X in their product and we don't -- we need to fix this." I'm not sure every feature should have something that looks like a mission statement but it would certainly elucidate the motivation for adding/modifying the feature in question.
> 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.
Whoever thinks comments are a code smell has probably stumbled into a nest of documented code where the documentation was out of date and didn't refer to the latest code in question, causing intense confusion. Comments can certainly be helpful but there is nothing to guarantee that they will be up to date or even useful.
Indeed. Had to port a 2k perl script with gigantic comment blocks written in German. Eventually I recreated the intended functionality with ~150 lines of JS after painfully google translating everything. JIRA references would probably be lost completely by the time I worked on it.
More around 800 of sloc. At least I haven't had to preserve bugs. There were also red herrings in the comments, leftovers as the script was tweaked to fit business requirements. Imagine blocks like this spat around randomly between code blocks...
###############################################################################
# #
# DAS IST CODE #
# #
###############################################################################
# #
# Das macht Dinge. Ja, ich habe diesen Übersetzer eingegeben, nur um etwas #
# einfügen zu können. Hoffentlich ist dies nach einer doppelten Übersetzung #
# noch lesbar. Wenn nicht, dann fick es einfach. Nett, es geht gut zurück. #
# #
# Natürlich wurde Interpunktion und Rechtschreibung gebrochen. Es war um das #
# Jahr 11, als der Übersetzer nicht über die gesamte Politur der künstlichen #
# Intelligenz verfügte, so dass eins von acht Wörtern nicht übersetzt wurde. #
# Zum Glück funktionierte es sogar mit Code, obwohl es nicht zu kompliziert #
# war. Andererseits sind Deutsche ziemlich zurückhaltend (oder waren, als #
# diese besondere Monstrosität gemacht wurde), um Englisch zu lernen, so dass #
# selbst Variablen in der Muttersprache sein mussten. Ich verließ das #
# Unternehmen rund 3 Monate, weil ich eine Legacy Monstrocity (es war nur ein #
# gehacktes Addon-Skript, das von einem Plugin-System in einem #
# Unternehmens-CMS lief) reparierte, war nicht meine Sache. #
# #
###############################################################################
Sorry to say that I'm one of those guys.
I never comment code that is straightforward and easy to understand if I succeed with naming classes, methods and variables right.
If I need to solve something in an illogical way due to other requirements/bugs that are out of my control I comment it.
I have read to many comments stating the obvious or that are just plain wrong.
No comments are better than comments with errors. The code is the only true fact.
> Sorry to say that I'm one of those guys. I never comment code that is straightforward and easy to understand if I succeed with naming classes, methods and variables right. If I need to solve something in an illogical way due to other requirements/bugs that are out of my control I comment it.
I think that's fine. I only comment code that is not obvious, breaks common idioms used in the code base or stuff that seems stupid but is actually needed because of legacy code or systems.
"Why" is what commit messages are for (and also comments); quality of commit message is worth checking in code review while the details are still fresh in everybody's minds...
What is the general opinion of CMM these days? I always associate it with UML diagrams for some reason. There was a time when the industry really wanted software to be fully specified. Seems like most people gave up on that dream, when agile came around and said "embrace change", along with the tenants.
But, alas, the pendulum swings. I think it's swinging back toward "I sure wish we didn't have to depend on finding skilled people, and our process was so bulletproof we could plug in any old schmuck and we can just continue to print money".
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.
Search is something that (with the advent of Teams) we've been bolstering our investment in. We've updated to the most recent version of elastic (which unblocks us on a lot of improvements) and we have upgraded how we are indexing questions/answers for Teams. and most importantly, we will just be continuing to improve it - since now it's more critical than ever to be successful there. To your point though, it's the first time we've invested in search in...well, I don't know how long.
Stack Overflow has very small experience with reusing the knowledge, aimed primarily at providing fast on-site answers, for questions too localized for reuse. I have doubts in its ability to provide a solid documentation base, given a flop it made of Documentation project. Wikipedia is a way better source of reusable knowledge than Stack Overflow, and for a reason.
I go to StackOverflow maybe 100 times more often, for coding related things, than to Wikipedia. Disagree that Wikipedia would be better — when it comes to softw dev.
Having said that, my gut feeling is that SO "Teams" product will succeed in enterprise (& small companies). Managers love if their employees take time to create "Summary pages" from the "Slack and other Chat products". But employees "do not have time" for "Summary pages" and there is no formal structure in 'Slack'. I think this Pages product product provide that 'structure' and a way to measure/monitor by manageres.
> 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 thought the primary goal of Stack Overflow was to crush Experts Exchange — that’s what Joel and Jeff said in the podcasts they published while SO was being built. I figured everything else it achieved was gravy.
>> And every single day several kids from elementary school start a new one.
So many StackOverflow posts consist of, "I searched how to do X, I copy and pasted the code from the StackOverflow answer that came up, and it doesn't work for me."
You can usually google a few lines of code and find out where they got it from originally.
Yes, and it makes Stack Overflow more like an imageboard than a documentation project. So I have doubts whether it can be used for the purpose especially with Google removed from the equation.
I think SO and pure documentation would serve two separate purposes. Sometimes documentation is better for something like an internal library API or related information. But on the other hand, sometimes having a an SO-like place where I can go look up a question related to a quick thing I'm trying to do would be useful. Say I don't remember the process to build the latest version of a Java package and upload it to an internal repository or something, it might be quicker to find a related quick Q&A type doc for that rather than digging into dense documentation on a variety of things.
And here comes the question of maintainability. For the code, we are trying to have a single repository to avoid duplicates and to have just a single place to make changes. That's what a wiki is good for. Whereas for such a dispersed knowledge base it would be hard to keep all these atomic questions up to date.
The front page for Teams boasts it's better than your "stale wikis and lost emails" but in reality there are much more stale answers on SO than anywhere else.
Also, in my experience, someone might proactively create a wiki page in the org documentation. But depending on the amount of logorrhea, it can be hard or discouraging for future people to change it.
Meanwhile SO answers are much more granular and easier to update for that reason.
For example, trying to transactionally update a large page on the org database system instead of an SO question about the parameters you need to connect to it. I can see SO winning here because the units of work are much smaller.
> In a wiki, at least I can follow the structure to find relevant pages
Wow! You have much more disciplined coworkers than most of us, then. I've been at my current employer for about 13 years now. We've gone through 3 or 4 different wikis. Right now we're split between Confluence (worst wiki software I've ever used) and an in-house solution. I can't find a god damned thing on either one. They're both awful, and so were the predecessors. Maintaining any kind of documentation takes work and our employer just doesn't give us enough time to do that and our jobs.
Confluence is one of the best designed products I've ever worked with. Makes the web behave like a native editor, awesome semantic macros that let you put in warnings or collapsible sections in a few keystrokes, you can generate page source with scripts.
Specifically regarding structure:
- every page has breadcrumbs letting you navigate up to its parents
- "child view" macro shows all children of this page automatically, so you can easily make a "category" page linking similar issues that is always up to date
- can move pages to new parents/spaces with a few clicks, or en masse with a drag-and-drop tree view
- built-in widget that searches only children of the page you embed it into
- spaces so you can tell a page in the search is owned by a different section of the team
Plus just a way lower barrier to entry than Wikipedia or the other wikis I've contributed to. I love Confluence.
"Confluence is one of the best designed products I've ever worked with" is something I never thought I would hear. Building a wiki is admittedly a very hard problem, but you're the first person I'v seen, that loves Confluence.
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.
Anyway, as I see it, as someone who has written quite enough if it, most software documentation is write-only 99% of the time; but it is occasionally very handy to have that documentation written by the original developers when shit really hits the fan.
"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.
SO dev here. Not sure your size, but your first 10 users are much cheaper. On signup, it starts at $10/month and includes the first 10 users. It's $5/user/mo after that.
I’m not sure I would want to work for a company that thinks spending an additional $5 is not worth improving my productivity. How much do you pay an engineer per year? You can’t afford an additional $5x12=$60, really?
This argument would make a lot more sense if it was $500 per month per dev, which some SaaS companies actually do charge per-seat for enterprise licensing plans. A $5 per user per month charge is actually an unusually low price for the enterprise SaaS market. In fact it’s even a low price for the individual developer market. Rarely does anything cost less than $9 per month...
I just figured this out, but that's $5/month for _active_ users. So if you don't use it, you don't pay for it. Not exactly sure what counts as an "active" user though.
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.
It's surprising how long code lives. In most organisations I have worked in, companies talk of rewriting legacy code but very few of these projects replace the existing code. There was a front-page article on Cobol here of HN a couple of days ago. Management tends to be interested in new features and I have noticed there is always a reluctance to change something that is already working.
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.
Those all sound like things that should be in perfect sync with the implementation. It would kind of suck if Marketing started talking about one way things work, when they actually work differently. The company sure as hell shouldn’t have Sales selling people based on things that aren’t true.
As I said in another comment, information extracted from code can be made more pretty but ideally the code is king.
No you totally want marketing to be talking about something in the same place, even if they are wrong. It would absolutely not suck if they posted something incorrect, because then the people that know better can post alternative answers and/or comment and help correct the information.
If you put them in separate stacks, the bad information will just persist and live in isolation, and never get corrected.
You basically want to do everything you can to prevent silo'ing of people as well as knowledge. You want people talking.
Consider too that not everything posted has to be about technology. It can be recommendations for a good restaurant near a customer site, or where office supplies can be found in a large, multi-site office, or how to request facilities to come fix a leaking faucet.
Ideally your deployments are code. And tutorials are part of your website 'code', or integrated into your project (and thus 'code'). General graphs of the architecture would be docs in your code repo (and thus 'code' too). I'll admit tho that it's pretty sensible to just not consider some of those as 'code' and thus conclude that documentation outside of the code is important too.
But the original commenter is also probably right that 'second hand' documentation is probably the least accurate.
These documents are still things that can become out of date. Anything of this nature can be in a source file somewhere, even if it’s a giant overview comment in one of the main files.
I do think it’s fine to create pretty docs from source comments or generate pictures from graph descriptions, etc. Every generated page should clearly state where it came from though (e.g. revision number and date).
Frankly I don’t like having only an API doc without the implementation. Code should be open-source to those using it, under NDA if necessary. When I need to rely on hidden implementations from Apple, etc. I routinely have to waste time discovering things simply not working as described. Meaning, their pretty docs are out of sync with reality and it wastes significant time to find this out the hard way.
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.
Please no, do not comment every function. Each function should average 5-10 lines, with clearly defined separation of concerns, and a descriptive name that inherently describes any writes/reads of the function. In the rare case where it makes sense to have a massive function, and you can’t break it into smaller functions within its scope, then maybe it makes sense to use a comment.
Adopting a policy of commenting every function header creates two major problems: (1) you now need to edit a comment every time you change a function, but your editor/compiler/rcs/ci will not inform you if you forget; (2) introducing a “typing tax” on creating new functions, since you need to write a comment too, actually discourages writing small functions because of the required comments.
The most readable code does not need comments, because you can clearly infer what each small function does by reading its header and local variable names. When looking at a set of functions, i.e. a class or file, you should be able to infer the “why” of each function by seeing it in the context of the other sensibly-named functions surrounding it.
Personally, my commenting policy is very simple: if I cannot infer the behavior of a piece of code by reading it, and I cannot change it to be more readable (usually for efficiency purposes), then I write a short comment explaining whatever is strange about it. This way someone reading through the code doesn’t need to slow down when they get to the grotesque portion, because they can just read the comment, assume it’s correct and double check later if necessary. Whereas if the code is littered with comments, you really can’t assume any are correct, which makes it difficult to read the actual code.
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.
But not positive. I vaguely remember it was a Python product. Not sure I can recommend it. I remember it not being nearly as polished as SO and not sure it's being actively maintained.
It's a shame that you can't use Stack Overflow itself constructively for this. I think Stack Overflow usage would be a great lesson for any introductory class. Just teaching new devs how to write a good Stack Overflow question is an invaluable step in problem-solving, even if they never post it.
Unfortunately, at the moment, I fear a good part of that lesson would be "the talk" about navigating the tricky culture of Stack Overflow.
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.
It's only "half the price" if you ignore the cost of Confluence itself. The Atlassian people are also historically awful at building out features that make hosting their products easier (for example, they've ignored a request for a "read only" mode for about 12 years now [1]).
The simple fact that it is a product that is made by someone other than Atlassian is a huge selling point.
FYI that we're implementing read-ony mode in our data center product line, and we've also got various knowledge base articles for how to achieve this should you need it:
I have never had the opportunity to tell anyone at Atlassian how much I love Confluence. There are so many cool technical feats that improve my experience, like being able to open an embedded spreadsheet in Excel and having it update the version on the page when you hit save. So many things that aren't natural for the web are seamless, like indent levels and accepting pasted images. So many organizational tools like excerpts and child view macro. So many usability features like attachment versioning and keyboard shortcuts.
It takes a great company to make such a great product so easy to use. Thank you.
"Questions for Confluence" surely benefits from its synergy with other Atlassian products, but it's not clear to what extent. Auto-linking of Jira tickets numbers?
Unfortunately for folks like me down in the trenches, the manager types typically have more sway when it comes to picking products like this. Expanding the Atlassian license to include one more product probably sounds much easier to them.
However, the $1.65 per user difference in price is likely not going to be a deal breaker for these decision makers if it can be shown that StackOverflow, the clear dominant player in Q&A, has a superior product.
I'd rather not learn a 9th Atlassian specific markup language.
I find JIRA and Confluence to be uncomfortably slow, even on high end hardware. I recall SO took a "scale up" approach but hopefully they can do better.
I 100% agree on the speed here. I thought it was just my inability to self host Atlassian products. I tried Atlassian OnDemand and the performance was actually worse compared to self hosting.
I legitimately don’t know if I’m just bad a “tuning” their stuff, but JIRA and Confluence in particular were nothing short of miserable to use daily. Bamboo was great, but it had a lot less daily interaction than JIRA, for obvious reasons.
I've used Questions for Confluence before. I've noticed that from the "supply side" (someone writing documentation), it's not better than writing a Confluence article. From the "demand side" (someone having a question), it doesn't beat the immediacy of Slack. So while I'm glad to have the option to have team SO, I'm not sure it solves the documentation problem better than other tools.
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.
If your goal is to post, then SO is excellent. But if your goal is also to read, there are questions. Nobody ever tried to use Stack Overflow without Google yet. given all its bell and whistles are intended for those who want to post, there are questions yet to answer.
I use SO without Google sometimes, in this way: I search for a phrase or tag, and read the 20 - 30 highest upvoted questions & answers about that — and I learn a lot, sometimes things that I didn't know, that I ought to know.
Well, I'm assuming it works like Stack Overflow. I can edit my own posts, but not those of others. Only high reputation moderators have the ability to edit other people's posts.
Here's how we coach moderators on the internal Stack-like site we run...
Editing
When editing content written by others, do so with respect to the person who is the original author of the content. Correct simple spelling and grammatical errors, but don't rewrite whole sentences or restructure some else's document. Instead, post a comment suggesting changes or corrections.
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.
That's Joel's version of link bait headline. It works nothing like a wiki. But of course, you already know that if you've used Stack Overflow. But, tomato, tomato.
a website that allows collaborative editing of its content and structure by its users.
StackOverflow is a website that allows users to edit the content of questions, answers, and tags. It also allows users to write new questions, new answers, and close existing questions and answers. How is that "nothing like a wiki"?
In his post here, he kind of directly writes that SO is not like a wiki.
> But you know what does work? A Q&A system. Like Stack Overflow.
> Why? Because unlike wikis, you don’t write documentation in the hopes that one day it might help someone.
In the exact quote you gave, he says that SO is different from "wikis" in that the question is written before the answer.
When most people think "wiki", seeing answers before questions is certainly a common characteristic they could assign to the concept, but it's not what makes it a "wiki".
I could design a wiki that was text-only and say, "unlike wikis, we don't present photos", but that wouldn't make it not-a-wiki.
Stack overflow was originally more like a wiki, with everything editable. Over time things got more immutable and marking questions as "community wiki" by default started being discouraged.
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.
We used mailing list per topic (think channels) that anyone could subscribe to, and piper mail for searchable archives, and a $100 bounty for every relevant topic turned into a GFM document (with guidelines for minimal structure w.r.t. pros and cons and whats, whys and hows). Seemed to work. Of course this was before people discovered Slack, destroyer of institutional knowledge.
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.
It was a weak joke concerning the usual complaints about SO and because I thought it was an on-premise offer, not integrated in the main SO site. As said below, there's no flagging in SO Teams.
If you need anonymous voting for decision concerning language/framework, I think you have a big problem: it would mean individuals are afraid of voicing their opinions regarding a technical choice and that's not something that can just be solved with a tool.
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.
Our documentation is split up between markdown files in-repo and a wiki (Confluence) with lots of assorted information. Interestingly we do the same kind of thing with an "experts" list, but with a focus for on-call engineers so they know who to contact if something's broken.
A lot of people still have a natural inclination to just post their questions in chat - probably because it's lower friction than typing up a question and then posting that in chat. We've been trying to shift this by re-posting people's questions in SO and answering them there. It's been mostly helpful, but I'd say we still have a ways to go in shifting people towards SO.
About 50 programmers, yes we've found that it wasn't natural for people to start asking their questions there and that we (the team that opened the beta) tend to seed Q&A there to drive people to the tool.
not yet. but supporting SSO options is on our near-term roadmap. however enterprise edition does support AD/SAML out of the box. stackoverflow.com/enterprise
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.
SO is a wiki. Except that instead of writing aimless documentation, you can document exactly what people are asking about.
Which makes it better than just about every wiki I've used at a company or Github repo which just get out of date because they are so arbitrary and unfocused.
Pushing my message again, but if you've not done so in a while, visit https://stackexchange.com/sites# and look at how many utterly non-technical topics are covered by this model. The application of the system is about far more than just traditional software development.
I think it's a mistake to look at this from the perspective of software developers. It's called "Teams" because it's for teams - which can be anything from software developers to facilities maintenance people. It's for teams that have questions (and answers), not for software developers who have questions (and answers).
By way of experience with this, we run an internally written Stack Overflow clone of sorts for a large industrial printing product we make. It's meant for people in our organization who have questions and are looking for answers. And as such, there are no "wrong" questions.
For example, someone might ask, "I'm traveling to the San Diego site - what's the most convenient hotel to stay at?", and create a new tag for "san-diego", "recommendations", and "hotels". Or they might post about "Top-of-form mark detected too close to the previous frame" using tags like "print-engine" and "top-of-form".
For us, both types of questions are very valid and "on topic" questions to post in our internal stack.
When we first launched our stack, we imagined it as being a kind of "crowd sourced internal knowledge capture" tool. But a real evolution in our thinking has occurred, and we've found that most people use it to post questions and answers at the same time. In other words, they've solved a problem and want to share the solution. And SO's "question/problem statement" followed by "answer/solution" template and framework makes it very easy for them to share this knowledge. Contrast with a wiki for example, where they are presented with a blank page and told to "document this issue".
One feature we are considering is the idea of wizards for certain types of posts. For example, if you are posting an answer about equipment work that requires opening electrical panels, we probably should have a warning about only doing this if you are certified for it. So the wizard idea might say, "Is this a solution that relates to electrical safety?" Checking yes automatically appends some boilerplate text with a caution about electrical certification.
We've also found that the voting up/down feature isn't that useful. People just don't do that voting stuff, nor do they really care about their reputation. What we are going to do is replace the vote system with a simple, "Did this answer help you?" type approach. It's literally the same thing, but with a different way of asking it. Because we don't actually do "down" votes, a "Yes" is a vote up, and a "No" prompts the user to post a comment explaining why it didn't help them, assuming it was what they were looking for. Was the answer not clear? Was it wrong? Did it not work? Is the information out of date? This kind of feedback (via comments) will help answer authors evolve their content to be better.
"Rest easy knowing that your Team’s data is secured in a dedicated network and logically separated into its own SQL schema. Learn more about our security policy. "
If its using logical separation on a shared SQL server, then is it really a "dedicated network"?
They used to do something similar to this, but then co-opted all the popular sites and shut down the rest. They had a parenting one that was pretty successful - probably because Jon Skeet was prolific on that one as well.
I feel like holding out single sign-on for a separate Enterprise tier priced at "Contact a sale rep for details!" is a mistake. Heck, I feel like any "contact a sales rep for details!" pricing tier is a mistake.
Why use this when Discourse is free? It is an open source product that lets you store all the data in your own database. And it’s by the same guys, too.
That plugin hardly turns Discourse into a full fledged Q&A site. It merely adds a button to mark a specific post as "The Answer". While that may be sufficient for many, there is a reason that StackOverflow has tags, tailored search, reputation, closing, etc. That's what they are selling with that $5 price tag.
It's funny you refute that forum add-on, as it is a good add-on, but it's also just an add-on. A band-aid, not a solution. Too often I see the selected answer "pulled up" to the top, but it's actually just the tail-end of a longer conversation, where the context of the conversation is critical to understanding the answer itself. Not to mention that comment responses (to both answers and the question itself) are interwoven together like a big bowl of spaghetti.
Meanwhile, I think StackOverflow, while great, is not living up to it's potential. I'm currently brainstorming/prototyping a StackOverflow alternative that covers the Q&A scenario, but adds support for more advanced features. If a question is opinion based, then you could have answers categorized into sides. Yes or No would be a common example. React vs VueJS vs Ember could be some side options in a question. OOP vs FP vs Procedural could be sides for another question. What is the right way to X can have a different answer depending on your "side", or it could be that the sides themselves are in disagreement. Sometimes it's nice to see and understand why another side prefers X. Let both side's top answers stand side by side at the top. Another idea is improved connecting of similar, but unmergable, questions. Another idea to connect questions by dependencies. A user could select some premises before asking, debates could be derailed less often by linking debunked arguements to their open debate page where there could be a large chain of custody on each element and nested prerequisite showing why it's wrong. Prerequisite could also be a word definition ("theory" is a random shower thought in some contexts, but in other contexts it's an explanation backed by so much evidence it's a strong candidate for established fact that could only be replaced by an expanded explaination, not an alternative one). Prerequisites could also be an axiom. In addition to questions, there could also be "claims". "Answers" to claims would basically be supporting evidence or refuting evidence.
And basically it would consist of claims and evidence linking to other claims — and automatically calculating scores based on votes for claims. The hardest problem would be to prevent sybil attacks, collusion and so on, that could compromise the voting system. Perhaps the score system would need to be based on something entirely different than voting, such as random polling to leverage the wisdom of the crowd (https://www.npr.org/sections/parallels/2014/04/02/297839429/...)
If you are interested, message me greg+hn then the at symbol then qbix.com
Discourse is far more open in scope. I could see wanting a SO-like documentation/knowledge platform without wanting a discussion platform with an add-on.
What would you expect to be different about a Discourse instance versus an SO instance?
I'd imagine they'd be almost exactly the same. Users post questions, other users (or the same user) posts an answer. The SO format isn't that different. And Discourse search probably works better currently anyways.
As others have mentioned in this thread, the SO-specific features seem least useful for small teams or really any organization that's not a bunch of random Internet people.
