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.
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.
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.
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.
# 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. #
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.
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.
Part of CMM level 5 process was things like 'Knowledge teams' which did exactly that.
Agile eat CMM for lunch though.
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".
Damn, the business man is greedy.
I love writing documentation from time to time. But this helps by getting you to write documentation for only things people are asking about.
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.
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.
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.
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.
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.
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.
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.
Citation needed. I use it almost daily and it's essentially write-only and pretty unusably so at that.
>... it's essentially write-only
Seems like there's no disagreement here :)
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.
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.
If you're much larger than 10 - creeping into the 200+ people, it might be better to go with Enterprise: https://stackoverflow.com/enterprise
I always have the impression that "Enterprise" plans are more expensive, but probably is just a misconception of mine.
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...
Sorry but that is just a ridiculous criticism.
Saves time and breath. Also serves as a mini-tutorial on the utility of the wiki.
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.
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.
As I said in another comment, information extracted from code can be made more pretty but ideally the code is king.
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.
Because an API reference is a very poor doc.
But the original commenter is also probably right that 'second hand' documentation is probably the least accurate.
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.
I also doubt that anyone could efficiently learn, say, CSS just by reading the Firefox source, revision history, and bugzilla.
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.
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.
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.
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).
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.
The simple fact that it is a product that is made by someone other than Atlassian is a huge selling point.
StackOverflow has the same issue here:
Many top requests are 9+ years old.
It takes a great company to make such a great product so easy to use. Thank you.
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 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 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'd encourage you to take a look again.
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.
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.
Teams users won't be able to edit answers?
Here's how we coach moderators on the internal Stack-like site we run...
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.
a website that allows collaborative editing of its content and structure by its users.
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.
"Because unlike wikis.."
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.
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.
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.
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.
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.
It's built on Django, and covers all of the standard Q&A features that I've needed to use.
It was already linked on HN:
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.
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.
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" feature or it's too deeply embedded in the psyche of the product.
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.
I suppose if a company had a paid librarian function, this could be successful. But in that case, even a normal wiki would probably work.
I seem to remember an article from Joel or Jeff many years ago describing why this exact model won't work. Can't seem to find it now though.
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.
If its using logical separation on a shared SQL server, then is it really a "dedicated network"?
Not bashing Discourse at all. In fact I wish I saw it in the wild more often.
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.
I thought of making a site like this called https://findmeaning.in
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
See slant.co, they have taken this approach.
Here's a good example, "What are the best co-op games on Steam?"
But you can’t have voting up and cute Q&A related badges, true. And reputation is also tricky.
But for many people, being able to own their own database for free will trump those things.
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.
>No more digging through stale wikis