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.
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.
Version control?
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.
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.
Citation needed. I use it almost daily and it's essentially write-only and pretty unusably so at that.
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
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.
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.
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.
[1] https://jira.atlassian.com/browse/CONFSERVER-6390?page=com.a...
https://confluence.atlassian.com/confkb/how-to-make-confluence-read-only-311920317.html
StackOverflow has the same issue here: https://meta.stackexchange.com/questions/tagged/feature-requ...
Many top requests are 9+ years old.
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.
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?
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.
https://www.joelonsoftware.com/2018/05/03/announcing-stack-o...
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"[1] feature or it's too deeply embedded in the psyche of the product.
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.
https://meta.discourse.org/t/discourse-solved-accepted-answe...
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