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.
Stack Overflow for Teams
111–120 of 163 posts
Re: Stack Overflow for Teams
#112Earlier quoted context omitted.
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 int…
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.
Re: Stack Overflow for Teams
#113Over 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 remo…
How do you fit deployment doc in code ? And tutorials ? General graphs of the architecture ? Because an API reference is a very poor doc.
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.
Re: Stack Overflow for Teams
#114Over 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 remo…
How do you fit deployment doc in code ? And tutorials ? General graphs of the architecture ? Because an API reference is a very poor doc.
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.
Re: Stack Overflow for Teams
#115My 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…
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 sourc…
> If I post an answer, only I can modify it.
Teams users won't be able to edit answers?
Re: Stack Overflow for Teams
#116Over 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 remo…
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.
Re: Stack Overflow for Teams
#117Why 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.
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.
Re: Stack Overflow for Teams
#118Over 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 remo…
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.
Re: Stack Overflow for Teams
#119Over 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 remo…
And yet, Stack Overflow has been massively successful.
I also doubt that anyone could efficiently learn, say, CSS just by reading the Firefox source, revision history, and bugzilla.
Re: Stack Overflow for Teams
#120There'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.
"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.
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...
Sorry but that is just a ridiculous criticism.