A couple of weeks ago we came to meta with a proposed expansion of Stack Overflow: Documentation. The response has been very encouraging: 2,400+ upvotes and even more signups for the beta.
You guys also asked a ton of questions. Some of them we were already kicking around internally, but weren’t quite ready to talk about, like versioning. Others hadn’t been on our radar at all, like the very name “Documentation.” We touched on a few of these already in the latest podcast, but we’ve got loads more to share today.
I’d also like to mention just how crucial this kind of feedback is to building a working feature, so thank you all!
Now for the questions!
To reiterate: all of this is very early and subject to change. Don’t take any of this as set in stone; we want to hear your feedback and we know we’ll have to make changes once we see all of this “in action” with real users doing real things.
What do we anticipate being “documented”?
This one was expressed a couple of ways (often implicitly) in conversations about whether tutorials were welcome, or if examples were the “point,” or if we trying to rebuild reference documentation.
Here’s what we’re thinking goes into Documentation:
- Chunkier “related task” pages about classes, modules, etc.
- For example: “Common mistakes using
Dictionary<T,V>
” could make sense as a page
- For example: “Common mistakes using
- Per member pages when they merit that detail
- For example: CreateProcess may be complicated enough to get a page to itself, but
Dictionary<T,V>.ToString()
isn’t
- For example: CreateProcess may be complicated enough to get a page to itself, but
- Short (single page) tutorial-like material
- Things like “Getting Started,” “Making HTTP Queries,” etc.
As was the case with what is on-topic for Q&A, I wouldn’t be surprised if this evolves over time.
How does this relate to official documentation?
First and foremost, we will not be portraying our Documentation as “official” in any way. We’ll treat it just like we do Q&A, clearly community contributed and curated, even if it’s been “blessed” by the owners (like many Google properties have done with Q&A).
There are also sometimes things that exist in official documentation that we don’t believe need to be duplicated, such as exhaustive lists of classes, methods, members, etc. Things that don’t require human curation or can be realistically autogenerated, basically.
How do we prevent pointless Documentation?
This came in two forms: concerns about preventing ghost towns, and “duplicate the existing documentation just to get rep”-behaviors.
We’ll accomplish both by having a pretty tight “someone actually requested this” -> “it was useful to someone” loop, and making sure reputation incentives are aligned with that loop. It will not be possible to earn rep just for posting or editing Documentation Topics or Examples.
For the loop itself, we’re making sure to collect Topic Requests and actionable feedback aggressively and promote it (see the top 2 tabs in the Dashboard mockup). We will also have a system for reviewing* changes before they go live (the third tab in the mockup), so you’ll have to convince additional people that new Documentation isn’t pointless.
*We haven’t figured out who, if anyone, will be able to skip review. It may make sense for a sufficiently trusted user to not require review, this is something we will figure out in the coming months.
How do we deal with fragmentation?
This was the highest voted concern. Our response builds on the questions addressed above.
First, it’s important to distinguish between “good” and “bad” cases of fragmentation. (I’m using fragmentation here to basically mean “related content on different domains/systems/whatnot.”)
“Bad” fragmentation is where you now have to check more places to get the same assistance as before. If, say, Oracle were to cut the Java documentation in half and put one half on a different domain in a different style and format that would be bad fragmentation. Similarly, if Documentation just made it so you now had to check MSDN and Stack Overflow for the same quality information you used to get just from MSDN that would be bad fragmentation.
“Good” fragmentation is where more or/and better quality content is available than was before. There are lots of examples of good fragmentation: programming blogs, articles, GitHub gists, podcast, and YouTube tutorials. It could be argued that javadocs-style websites themselves are a mild case of good fragmentation; they’re just formatted copies of what you could read in the source after all. If Documentation is truly useful and of higher quality than what’s readily available today, that will be the good kind of fragmentation.
So how will we handle bad fragmentation? Our response is two-fold: discouraging “bad” fragmentation in the first place and then dealing with what slips through anyway.
A key point here is that the community is going to determine what Documentation exists. If most everyone’s satisfied with a project’s existing documentation then there won’t be requestors, contributors, or consumers so there won’t be much in the system. And if the community comes to think that some Documentation is best removed from the Internet, that is within their power (just like question, answers, users, and tags can be deleted). Aligning reputation incentives such that we reward Documentation that is being used adds a second pass of filtering, as people will be inclined to focus their efforts on what is being underserved by existing resources.
For dealing with what bad content gets through anyway, we’ll have a system of voting and flagging that escalates Topics & Examples for further scrutiny. We’re starting from day 1 with a notion of “this needs to be looked at”-action items (the Needs Improvement tab in this mockup; not in love with the name, honestly), for this purpose. That tab will be for more than just preventing “bad” fragmentation - it’ll also be used for preventing copy/paste, bad information, fixing out of date information, vandalism, etc.
As an aside: we think that what Stack Overflow did to Q&A is an example of “good” fragmentation. There was programming Q&A before us, and still is after us, but we improved the Internet quite a bit anyway. Hopefully, together, we can make Documentation improve it again.
How does versioning work?
This one was asked a bunch, and we’re all in agreement that it’s pretty important to have a good solution at launch. When the initial post was written, we had plans but not much to show. Now we have a little bit to show.
The gist is, every tag (which has Documentation associated with it) will have a list of versions associated with it. Each Topic page can have a subset of that list attached to it, and any block of Markdown code within a Topic can be marked as particular to a version. When a new version is introduced, we’ll assume that anything on the previous version is still supported. We’ll use this information for display purposes, as well as for search.
Some mockups of what it’ll probably look like.
Marks the whole Topic as defaulting to the selected versions
What’ll be shown when you mark just a block in the Markdown
We’re still working on displaying multiple versions, but we’re pretty sure it’s going here
How will new releases / outdated content be dealt with?
This ties into the versioning questions.
The short answer is: flagging. We’ll escalate these “this is out of date” flags up to the Dashboard like all the other flags. We’ve also played around with some “auto-flag for review when a new version is released”-ideas, but we don’t have anything concrete at this time. This is one of the things I’m hoping the betas will help us iron out.
What about hierarchies, nesting, grouping, namespaces, modules, etc.?
This question was asked a couple of times, but there was also a point raised a few times which is basically its answer: the default way people search for and through documentation is they google it.
To illustrate, I went and grabbed the last couple of times I hit MSDN:
You might notice a bit of a pattern.
We don’t really think, based on observation and personal experiences, that there’s a ton of value to be had in strict hierarchies. They also add big points of contention and debate, plus some serious technical issues (like, what happens to Topics when the hierarchy is modified, who can modify it, how do you modify it?). The tradeoffs don’t make much sense, in other words.
What is super important is linking. Lots of information is conveyed, and links are very flexible. We intend to strongly encourage links, and to make intelligent “Related Topic” inferencing based on it.
We’ll be surfacing that data in the search box at least, and perhaps in other places:
As with many things here we may find out that we’re wrong in beta, but for now we’re pretty convinced this approach is promising enough to try.
What about a different License?
Our goal is for anyone to be able to use our content (Q&A and Documentation), provided they attribute the author(s) and Stack Overflow in a reasonable manner. For now CC BY-SA is how we achieve that. This means that any project that has associated Stack Overflow Documentation will be able to safely reproduce it, as a practical matter, though the license may not match their existing documentation license.
Concerns have been raised in the past about our license, and we do reevaluate our options periodically. Options that are routinely floated have significant issues, unfortunately, so we haven’t come up with an improvement yet. These things move at the speed of law unfortunately, but we have been actively investigating.
How do we prevent plagiarism?
This was raised a couple of times, often with reference to tag wikis.
Tag wikis get very little visibility (which is just one of the many… issues with that feature), which I think is the root of the plagiarism problem we’ve had with them. We’ll be doing many things to increase the number of eyes that see Topics - like requiring reviews for many changes before they go live, and making it easy to flag copy/pasted content for additional review. We also intend to do some first-time contributor education, and a “don’t just copy/paste, we’ll delete it”-bit is going in there.
Where would Documentation "live"?
Added 2015-09-21
This wasn't actually on my radar, but enough questions have been asked since this was posted that it probably should have been.
Documentation is envisioned as a new section on the Stack Overflow site. Exactly what that navigation will look like is still being debated, but for now a reasonable approximation is "a [Documentation] tab up between [Questions] and [Tags]."
We think this makes more sense than a new site because of how we're expecting Documentation and Q&A to complement each other. Many Questions and Answers will have links to Documentation, many of the same users who post Answers will contribute to Documentation, and tags serve a similar organizational purpose for both Q&A and Documentation.
There are some technical benefits to this approach as well, mostly around login and future TLS support. Another minor benefit, for now, is that the "add-on to an existing site"-model doesn't inhibit efforts to expand Documentation to the rest of the Stack Exchange network.
Is Documentation the right name?
This is a tricky one, as there seems to be a fair amount of variance in what people consider documentation to be. Are the long form articles on MSDN or http://www.oracle.com/technetwork/java/ documentation? What if they’re linked from a class’s page? And so on. “Tutorials” or “Examples” feel too limiting, at least to me, considering that some type/member-level documentation will almost certainly exist.
For now we’re sticking with the Documentation name, at least until the beta starts, but we are taking suggestions.
What about offline reference?
It came up a couple of times, but this one’s easy to answer: we’ll have print stylesheets, and Documentation will make its way into data dumps and the API eventually.
What about small screens, tablets, phones and mobile?
We will eventually have mobile web themes for Documentation, but probably not during the betas. Documentation won’t be incorporated into our mobile apps until the whole feature is pretty stable, due to the longer release cycle imposed by app stores.
Why is Documentation focused on Stack Overflow, instead of the rest of the network?
It is much much easier to design something this complex with a single, focused, problem in mind. We also want to keep our iteration times pretty short once we hit beta, which means the fewer use cases we have to keep in mind the better.
But we haven’t precluded expanding Documentation to other non-Stack Overflow sites in the future, nor have we precluded making customizations at that time to better fit the feature to those other sites.
And that’s it! I’m sure there will be more questions, and we’ll have more answers as we get closer to the private beta. Once again, thank you to everyone who’s provided feedback so far and do please keep it coming!
You Can Still Register For The Beta
We’ll need to know three things:
- Your email
- Your Stack Overflow profile URL
- A list of 2-5 tags you’d be interested in helping document
Please pick tags from the first two pages of popular tags that have an especially active community. Things like c#, r, or ios so we can test our system out against the real things that lots of developers are using in the private beta.
Registration will be open until the private beta starts. There is no minimum reputation or time commitment requirement.