360

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
  • 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
  • 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.

Assign versions while editing title Marks the whole Topic as defaulting to the selected versions

Markdown level tags What’ll be shown when you mark just a block in the Markdown

Showing versions on the Topic 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: History to 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: Search behavior

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 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 , , or 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.

Register and help Make Docs Suck Less

50
  • 19
    Cool! Always nice to hear reports on progress as it happens. I've been practicing writing documentation to get myself into the groove. Commented Sep 16, 2015 at 17:31
  • 1
    This is great to see, I appreciate the effort you guys are making to put this sort of information/answers out there. Looking forward to it!
    – enderland
    Commented Sep 16, 2015 at 18:52
  • 43
    I know this seems like a small thing, but support for anchors is a huge, huge boost to readability and usability of documentation. It's something that I wish I've been able to put into long answers for a long time on Stack Overflow, and will be sorely needed on the Documentation site. Will we support anchor markdown?
    – durron597
    Commented Sep 16, 2015 at 20:05
  • 18
    @durron597 in our current code every heading (including markdown ones) and example has an accompanying anchor. Commented Sep 16, 2015 at 20:12
  • 3
    Thanks for investigating possible licensing alternatives. I appreciate that this is complicated, messy, and may not be practical in the end, but am happy it's being considered.
    – Jeremy Banks Mod
    Commented Sep 16, 2015 at 20:53
  • 2
    "It will not be possible to earn rep for just posting documentation" - but if rep doesn't matter and we feel compelled to share documentation on something, we can post it without being asked, correct?
    – corsiKa
    Commented Sep 16, 2015 at 21:25
  • 5
    Is this warlord thing part of the name? Not proposing "Peacemakers of Documentation" but the world is already as bloody as it can get. I really don't find any fun in this word as it brings me afghan or congolese or mexican images straight to the mind.
    – brasofilo
    Commented Sep 16, 2015 at 23:13
  • 5
    @brasofilo I think it's just a codename for the project of adding the feature. (Someone's been playing a lot of WoW, I imagine.) The feature itself will probably be named something simple like "Stack Overflow Documentation", unless someone suggests a better name.
    – Jeremy Banks Mod
    Commented Sep 16, 2015 at 23:26
  • 2
    Could you please make the whole system multilingual by default? So that multilingual content can be provided?
    – Uwe Keim
    Commented Sep 17, 2015 at 7:54
  • 5
    Just like SO the path to rep will be splattering the place with information related to JS/Java/Go/[today's-buzzword], no matter how trivial or shallow; and doing heavy lifting in business-critical-but-not-cool-this-week areas will go largely unnoticed. There is a treacherous network effect here that prevents community interaction from ever reaching SO Q&A in some of the areas Q&A is needed most. This will extend to documentation as well. With no rep attached, interaction in MLs and IRC is more rewarding (and not subject to the Idle Mod Mafia) in "non-mainstream" communities. No 親子丼.
    – zxq9
    Commented Sep 17, 2015 at 10:08
  • 1
    After reading this follow-up post, I'm feeling more confident about the whole idea and I've signed up for the beta :)
    – user247702
    Commented Sep 17, 2015 at 14:57
  • 3
    @UweKeim we're building it using the localization tools we developed for the localized SO sites. While we'll be launching on English Stack Overflow first, localizing should follow quickly once the system has settled down. Commented Sep 17, 2015 at 17:17
  • 1
    @brasofilo Warlords is a pun on the last WoW expansion. I don't actually play, but thought it was a funny enough pun to run with as a joke for the meta posts. The actual feature is not named and will not be formally announced (like, on the blog) as Warlords-anything. Commented Sep 17, 2015 at 19:49
  • 2
    What about devdocs.io ?
    – Epoc
    Commented Sep 22, 2015 at 16:02
  • 7
    Apache projects need apache licensed documentation. GPL projects need GPL licensed documentation. You cannot integrate BY-CC-SA documentation into Apache JavaDoc. Step out of your MSDN view! I'm not going to contribute here, unless this licensing mismatch is fixed, and the system is designed to improve upstream documentation. Because I love F/LOSS. Commented Sep 23, 2015 at 21:06

20 Answers 20

77

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.

The implication here is that a document can only be created if it is initiated somehow by one person, but filled in by another. Policing of the "someone actually requested this" then becomes necessary: a "doc ring" (or duo), or an old-fashioned sockpuppet can still farm reputation points.

More importantly, I don't see how this works with the existing idea of self-answering in Q&A-land. Is that concept not going to be transferred? I think that would be a shame; there's no reason that I can see for an expert to not be able to produce an "example" page from scratch. That's the stuff of the "programming blogs, articles, GitHub gists" that you mention: I just figured out how to wrangle $FRAMEWORK into doing a tricky but worthwhile thing, and a) I'm going to have forgotten in three months and b) other people have probably wondered how to do it/will wonder when they see my cool application, so I should write the procedure down somewhere.

If I'm reading into "someone actually requested this" correctly, I'm not sure it would be a good requirement. The problem of triviality/plagiarism seems to be essentially the same as that for Q&A, but this solution looks like it would hinder experts from producing useful documents.

10
  • 8
    Yeah, what if I just want to write a document to fill in something I already know how to do, but for which there's not really any quality documentation out there to direct users to? Take, for example, game development libraries. There are a huge number of topics in game development, many of which can be realized with a specific language by using a specific library. However, game development is hard enough that most people won't take the effort to make a working tutorial of some game mechanic/technique with some library... but goddamnit, I want rendering-to-texture in Ruby, and I want to share. Commented Sep 16, 2015 at 19:56
  • 5
    Off-the-cuff suggestions: (a) Make creating pages from scratch a somewhat hard to attain privilege (e.g. require 10k rep or a silver tag badge); (b) Allow recognised experts (e.g. major contributors to relevant projects) to create new pages; (c) Set up a migration path for self-answered questions. These workarounds are complementary to each other. Some potential objections: (a) would exclude experts who are not interested in building up rep, (b) might lead to bureaucracy and drama, while (c) would require some extra editing work.
    – duplode
    Commented Sep 16, 2015 at 19:56
  • 7
    I'm not sure if making from-scratch page creation restricted to the ivory tower of high-rep users is a good thing; rep != expertise, especially when it's low. Commented Sep 16, 2015 at 20:01
  • 41
    It sounds to me like doing the things people request gets you rep, and getting up votes when people find it helpful gets you rep, i.e. making the page from scratch = no rep, but people up-voting its usefulness = rep Commented Sep 16, 2015 at 20:38
  • Ah ha; that would neatly sail between the rock and the whirlpool, @BenKnoble. Great clarification.
    – jscs
    Commented Sep 16, 2015 at 20:45
  • Hallelujah for greek references. Scylla and Charybdis. Commented Sep 16, 2015 at 20:47
  • 2
    Why not put a documentation request up to voting, and only allowing it after some threshold?
    – Governa
    Commented Sep 17, 2015 at 20:28
  • 3
    As with self-answered questions, I don't think there's any pressing need to prevent self-created articles, so long as there's an opportunity for the rest of the community to review their content.
    – Ajedi32
    Commented Sep 17, 2015 at 21:14
  • 2
    If someone wants to spend their time making useful documentation in order to "farm rep", I say let them.
    – Suragch
    Commented Oct 1, 2015 at 9:59
  • 1
    Yes, the key word being "useful", @Suragch.
    – jscs
    Commented Oct 1, 2015 at 16:22
60

I didn't ask this in the main page because I got there late, but what will the moderation model be for this new site? Will there be separate elected moderators? Will there be interaction with the existing Stack Overflow moderators?

Will there be a separate Meta site for proposed changes to this site, or will that be handled by Meta.SO as well?

It sounds like spam and offensive content will be handled by the fact that new documentation will need to be approved first. Where will we draw the line for companies that write documentation for their products just to direct links back at them? We've had many cases of people using questions and answers on SO to seed a FAQ for their products in a way that really pushed the limits for self-promotion. At the same time, we want people from Microsoft, etc. to be able to help with documentation for their products.

How will we handle people who are terrible reviewers and who approve everything? How will people who spam edits just for reputation be handled?

The tools we have for moderation have been built and tuned for a Q & A system, and I'm curious as to how much of that will translate to a very different format. The above is more question than concern, so I can convert this to a full Meta.SO question if you think that would be more appropriate.

5
  • 15
    Current assumption is that existing Stack Overflow moderators will also be moderators for Documentation purposes. I'm hoping (Documentation's version of) review can be tuned to keep diamond-mod work pretty rare. We aren't planning to make drastic changes to the existing mod tools (which are Q&A focused), but rather to build new ones focused on Documentation as they are needed. Documentation will live on SO's domain, and use the same meta for discussion (once out of private beta anyway; we'll segregate while we're breaking everything). Commented Sep 16, 2015 at 18:34
  • 8
    A somewhat meta note: it's hard to anticipate quite what moderation problems will arise (beyond the super obvious spam and vandalism issues), so I don't want to invest too much in diamond-mod-only actions for Documentation until we can observe problems in the real world. Otherwise there's a good chance we'll waste a lot of dev time that could be better spent elsewhere. Commented Sep 16, 2015 at 18:36
  • 11
    @KevinMontrose - That makes sense. If we have access to the same tools for managing accounts, and it's tied to someone's SO account, we can deal with rudeness, spam accounts, etc. in the same way we do now. Edit conflicts, Wikipedia-style, could be the biggest new moderation problem with this system. Be interested to see how that goes down when things are live.
    – Brad Larson Mod
    Commented Sep 16, 2015 at 18:44
  • 5
    "How will we handle people who are terrible reviewers and who approve everything?" By not making reviewing attainable by all users. We really don't need to give everyone that ability.
    – BoltClock Mod
    Commented Sep 17, 2015 at 7:36
  • @BoltClock I'm assuming you're talking about restricting reviews to the existing model, and making it dependent on rep? Commented Sep 21, 2015 at 14:35
48

Why do we have to gamify this?

Let's face it: within 24 hours of the site's launch, it's going to be a rat race.

People will write and amass troves of original examples days before the site is even launched, and then once it's launched copy and paste all of their content as quickly as possible to the site with the simplest of examples (and most useful, especially for newbies) like Arrays.sort() so that they will be wealthy in rep forever!

How many seconds will it take somebody to create a doc for Hello World!, and how much rep are they going to get from that?

Now let's look at this site five years on:

  • Popular APIs will be filled to the brim with as much information as possible, and inevitably those who created the content first will get the majority of the rep.
  • Developers of APIs will have ceased putting as much effort into their own docs, as they can just point their users to "Doc Overflow" and let the community take care of the rest.
  • New information on APIs will have exhausted very quickly. Stack Overflow models its reputation system under the idea that every user has a fair chance of answering questions, and the community will never run out of questions to ask or answer. Unfortunately, libraries take a little bit longer to write, and without new libraries, there will be no source material to document.
  • As a consequence of the last point, it will have become increasingly difficult for new users to earn rep, as their only choices are to edit documentation ("but what if it's already perfectly written?") or to document obscure APIs, which they will never earn rep out of if it is useful to less than a hundred users.

We can't quantify how knowledgeable somebody is on X subject, if that person doesn't get a chance to write new info on X because all useful information on X has already been written. Moreover, if somebody gets 500 rep from writing something very concise yet very useful, how can we determine how knowledgeable that person is on things other than a few key points?

Consider Wikipedia, another website powered by knowledge. Anyone is welcome to pitch in anything they know on the matter or just restructure the article, and moderators hardly intervene in the editing process because the vast majority of article don't need edits approved due to the existence of well-tuned bots that detect and remove spam. But unlike SO, Wikipedia is not powered by a desire to boost one's ego with an arbitrary number! Most users don't show off their contribution count, and you can't see the total number without using a script, because they don't care, and neither should this community!

Let's just spread knowledge without backstabbing each other with elitism.

9
  • 3
    I think your question and last statement is causing you to get more downvotes, and your precieved view of SO's rep system which I have no real problem with, but I actually upvoted this as it (the questions: "how difficult would it become for new users signing up late to earn rep compared to the first set of users" & "how do we balance rep gain due to the varying popularity of different APIs/Features - or do we care to balance it") is interesting. Commented Sep 20, 2015 at 1:54
  • 22
    Developers of APIs will have ceased putting as much effort into their own docs, as they can just point their users to "Doc Overflow" and let the community take care of the rest. Why is that bad? - it will have become increasingly difficult for new users to earn rep, as their only choices are to edit documentation to paraphrase Shog9, all good content eventually having been written down and nothing being left for new users (as unrealistic as that is) is a pretty darn good problem to have....
    – Pekka
    Commented Sep 20, 2015 at 19:48
  • 11
    One of the major factors that made Stack Overflow great was its gamification. And looking at where it is now, it has worked tremendously well, for all the system's flaws (including the widespread silly assumption that rep is always proof of actual expertise). If we want a documentation database that is like Wikipedia in that users don't have an arbitraty number next to their name then let Wikipedia do it.
    – Pekka
    Commented Sep 20, 2015 at 19:50
  • 5
    @Pekka웃 It would be bad because the API developers are the ones with the best knowledge of the API: what it actually does, what it's intended to do, what "features" are actually bugs that aren't reliable to depend on, etc. Relying on the SO community to reverse-engineer every API is less optimal than having the developers provide good documentation to start with. -- That said, poor API documentation is the norm, so SO's contribution to lazy developers skimping on documentation will probably be minimal.
    – R.M.
    Commented Sep 20, 2015 at 21:01
  • 3
    @R.M. My personal experience is that while API devs know what the API does the best, they can be among the worst at knowing how to use the API in real-world projects...because in many cases they simply don't use it. My hope is that whenever there are semi-decent official docs, the topic requests here will focus on examples, tutorials, integration with other tools, and other stuff where the API's users have a competitive advantage over the API's devs.
    – Ixrec
    Commented Sep 22, 2015 at 23:14
  • 9
    i used to think like this, but honestly.... what you've just said is that the gamification causes a lot of people to add documentation to the site really quickly, to the point where it quickly gets to the point where there's not much useful to add. that doesn't seem like a point against it... that seems like it's working as intended.... Commented Sep 24, 2015 at 2:22
  • 4
    (1) Whether to add gamification isn't (just) an ethical choice. Gamification is one of the main moderation mechanisms of SO. Removing it from some part of the site would make it necessary to add something else in its place, which would likely mean extra bureaucracy. (2) Wikipedia is a wonderful project, but it is no utopian paradise.
    – duplode
    Commented Sep 27, 2015 at 16:22
  • 1
    Are you saying that people will stop writing new libraries?
    – Jehan
    Commented Sep 28, 2015 at 18:17
  • 2
    I'm not against the gamification of this new document system, but it would be nice for contributors to have the option to selectively forfeit reputation earned for their contributions (sort of similar to how people can choose to make posts community-wiki now). With gamification, I would feel that every change I make to the documentation would need to be substantial, so that people wouldn't accuse me of purposefully making small edits to gain rep. If I can forfeit the rep gains, then I'm more inclined to go ahead and make smaller edits.
    – user456814
    Commented Oct 3, 2015 at 3:32
32

There is one major question that was not answered yet:

When will the private beta begin?

(so we can start breaking things)

Will it be in 1 month, 6-8 weeks or 6 months? I would like to know the internal schedule that you have in mind.

2
24

What is the scope of the intended documents?

When do we narrow, and when do we broaden the scope?

If a user asks for a "Getting Started" guide on a specific library or framework, how does that differ in scope/intent from a "Getting Started" guide on an entire language?

Given the above scenario, do we know what they are really asking for? Are they asking for a tutorial? A guide? A step-by-step walkthrough of how to set up their environment?

Perhaps I'm overthinking this, but perhaps not, since it's genuinely something that can happen on the site. Do we say, "Yes, we're fine with a user asking for and writing up an entire introduction to a language", and deal with its inaccuracies/nuances/completeness later, or do we reject that at the front door?

Help set my expectations here.

2
  • 2
    Yeah, this is one of the things that I've been a little confused about. My thoughts on the subject are that it could be left to the community as well, giving people the ability to flag for dissolution into multiple topics, along with the ability to link back to the dissolved parent version as part of each resultant topic's history. Of course, this opens up a whole new set of challenges regarding how this behavior is moderated, controlled, and represented. Commented Sep 16, 2015 at 19:35
  • 1
    Perhaps a flag for requests to mark them as "needing clarification" (in the same way a question can be put on hold for being too broad) and if the original requester doesn't clarify what they are looking for then the request gets removed. Another possibility could be having different types of docs requiring more reviews - "Getting Started" could require a lot as it would be quite broad and needs to be very well written. This does then add the issue of marking docs as being of a particular type/style...
    – Kvothe
    Commented Sep 16, 2015 at 23:08
21

This is closely related to, but not the same as, the concerns of fragmentation and duplication:

Will SO-generated documentation be pushed back upstream to the project it is documenting? How, and by whom?

As a matter of ethics, I am only comfortable with this proposal if it includes mechanism, policy, and staffing to ensure that documentation does get pushed back upstream, particularly when documenting open-source software. Moreover, a passive "well, it's here if you want it" is not good enough. If this is going to happen at all, I think it is the Stack Overflow organization's responsibility to actively reach out to each upstream project to to get permission to contribute docs, work with them to figure out what is most useful to them, and then continually provide them material.

Note that this also entails mechanism and policy for conforming the licensing of SO-generated documentation to each upstream project's preferences.

18
  • 5
    Its licensed CC-SA, so project maintainers can push upstream as long as they cite us. Commented Sep 17, 2015 at 16:24
  • 2
    It would be smart for SO to create integrations and tools for doing so. SO is not going to have permission to do it themselves, however could create tooling for others to do so.
    – dthree
    Commented Sep 17, 2015 at 16:24
  • 2
    I may not have been clear: I think it is the SO organization's responsibility, as part of this plan, to actively reach out to each upstream project to get permission to contribute docs, work with them to figure out what is most useful to them, and then continually provide them material. Passive "well, it's here if you want it" is not good enough.
    – zwol
    Commented Sep 17, 2015 at 17:22
  • 1
    (I'm okay with not trying all that hard with the outreach for commercial software, and I'm okay with SO-exclusive documentation where the upstream project is not interested in cooperating.
    – zwol
    Commented Sep 17, 2015 at 17:25
  • 5
    In that case, why is it SO's responsibility to do this? Why is this "a matter of ethics"? If the users who create documentation here felt that strongly about it, one would think they would just help curate the "official" documentation in the first place. Commented Sep 17, 2015 at 23:33
  • 8
    @BradleyDotNET A system like this may well draw people away from contributing documentation upstream because it's just so much easier. That tendency has to be counterbalanced.
    – zwol
    Commented Sep 18, 2015 at 0:12
  • 5
    I think it is the SO organization's responsibility, as part of this plan, to actively reach out to each upstream project to get permission to contribute docs, Given that there's tens of thousands of different documentation systems, formats, formatting, structuring and wording styles, requirements, guidelines, editing cultures, and more, this is a spectacularly unrealistic requirement. As long as there's a super liberal license and a super easy way for project maintainers to import/update content, why insist on something as crazy as actively reaching out to a million people?
    – Pekka
    Commented Sep 20, 2015 at 19:55
  • 1
    A system like this may well draw people away from contributing documentation upstream because it's just so much easier. true - projects that use a sucky documentation platform may indeed suffer. In the long run, though, that's going to be a good thing for the mission of software documentation in general. When faced with this, it's the individual projects' maintainers' responsibility to either provide a system that is as easy to use as Docs.SO, or see to it that the content generated there is reintegrated into the main docs, in the style that suits the respective project.
    – Pekka
    Commented Sep 20, 2015 at 20:03
  • 3
    @Pekka웃 Because I consider this mandatory as a matter of ethics, I do not care how difficult it is; if the SO corporation is not up to the challenge then it shouldn't be undertaking this project at all.
    – zwol
    Commented Sep 20, 2015 at 20:05
  • 5
    @Pekka웃 In the long run, though, that's going to be a good thing for the mission of software documentation in general. Disagree. It could easily happen that this project comes to monopolize good documentation, and then turns into a sucking swamp of bureaucracy and tinpot dictators a la Wikipedia, thus putting all new contributors off writing documentation ... forever. (SO itself is already well down that road.) Active efforts to push docs back upstream can at least mitigate this risk, by avoiding taking all the oxygen away from those projects' documentation teams.
    – zwol
    Commented Sep 20, 2015 at 20:09
  • 2
    @zwol but what would this look like in practice? SO staff editing hundreds of different CMSes and platforms? Who should/could/would pay for that? Why relieve maintainers from what is their responsibility?.... I see your point about Wikipedia and SO, but both places are, for all their faults, arguably still a net benefit to mankind. They have revolutionized access to info, each in their own way. If a docs platform like the proposed docs.SO becomes big enough to have those kinds of problems, it'll have become a net benefit to mankind, too. Let's worry about bureaucracy when we get there.
    – Pekka
    Commented Sep 20, 2015 at 20:19
  • 2
    @Pekka웃 What I hope this looks like in practice is SO staff, as part of the build-out, developing tools that let the community identify particular pieces of WD documentation as high-quality and addressing a gap in upstream documentation; automation such that whenever this happens for an upstream that has opted into the process, they get a pull request or equivalent; and finally, ongoing outreach and dialogue with upstreams so they know that this stuff exists and we know whether or not it is meeting their needs.
    – zwol
    Commented Sep 20, 2015 at 20:27
  • 1
    @Pekka웃 It is fundamentally the same as the difference between "throw it over the wall" and actual open development of free software; or to put it another way, this is what makes this a project in cooperation with other projects rather than a landgrab.
    – zwol
    Commented Sep 20, 2015 at 20:28
  • 2
    @BradleyDotNET The "share alike" clause means that it's more than just "as long as they cite us". There's potential legal issues for projects who either use a more permissive or more restrictive license for their documentation. -- That might be what some contributors desire, but let's not pretend it won't exist.
    – R.M.
    Commented Sep 20, 2015 at 20:51
  • 2
    It may be impossible to integrate CC-BY-SA documentation. E.g. JavaDoc is covered by the existing source code license. So none of the documentation will be allowed to be integrated back into any of the Apache or GPL Java projects. Bad fragmentation. Commented Sep 23, 2015 at 21:04
19

Why is requesting documentation better than asking it as a question on Stack Overflow?

Don't get me wrong. I like the idea of that Stackumentation, but as far I understood it, documentation seems to be good when someone asks for it. Writing documentation takes much longer than writing an answer to a question on Stack Overflow. IMHO, most users want a fast answer which solves their problem as soon as possible. What is the advantage for the user to ask for it?

Will a documentation request get a review or a vote limit before starting documentation?

I can imagine some cases where documentation can be pointless:

  • A user don't understand the documentation and asks for a new one.
    I see here two options:

    1. Document it anyway since it might help others
    2. Just help that user with a simple explanation
  • A user doesn't find the documentation because she or he uses a blob without documentation.

Possible solutions:

  1. We could give hints on how to improve the Google skills to find the documentation
  2. Document it just because Stack Overflow has a better search rank than the original documentation or other helpful resources

Both problems might be solvable with a limit before starting the documentation or a review, so that pointless requests won't trigger a creation of a documentation. What do you think about it?

1
  • 1
    For the most part I agree with you, but I think there is definitely some kind of space for long-form answers e.g. the difference between 'I don't understand how the API for this library works, what's wrong with this code' and 'can someone post an example of how you'd use this library to accomplish something like this?' The second is a little too general for SO, but perfect for this new area, maybe. Commented Sep 24, 2015 at 2:24
15

Will there be a full revision tracking system?

Everyone knows that the revision tracking system currently employed by the Stack Exchange network is... lacking. My question is will we get a full revision tracking system for Documentation or will we be stuck with old faithful because it doesn't really matter, most users won't look at the revision history anyway?

1
  • With my "Stackumentation" idea of doing a raw data + compositional views, full revision is a natural part of the solution. This is exactly analogous to event-sourcing having full history for domain object tracking.
    – user4275029
    Commented Sep 21, 2015 at 11:53
14

How will the line be drawn between "how do I" and "do this for me"?

If working in a topic, and there is a request for documentation or an example, will there be ways to remove requests, close them, or vote on them, or somehow ensure that there is quality control there?

If the requests turn into spam or are abusive, can we flag them? And also, for clarification purposes, will each request for an example or topic have a comment section in case the request is vague, too localized, or not really on topic?

Given these points, how will this aside from a search interface and new UI, be any different than the current setup of separating by tag, posting questions, filtering questions based on votes and closures, and placing answers with examples to those issues?

1
  • 1
    I'd imagine that they would just age away if no one is interested in the request... But I love closing things so +1.
    – user4639281
    Commented Sep 17, 2015 at 23:01
14

I believe this addresses quite well the concerns in my answer to the first post. The key quotes are...

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.

... and...

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.

... which effectively rule out the possibility of using the material here as a drop-in replacement for reference documentation. That largely covers the issue of blurring the lines between primary and secondary sources, and also brings the project closer to "good fragmentation".

I still think calling it "documentation" feels a little odd, but that is a minor issue, specially given that there is no obvious satisfactory alternative. "Documentation commentary" (with "commentary" being used in the humanities sense of "explanatory or critical notes on a text") would be accurate, but of course that is not a reasonable name for a project.

8
  • Documentation Commentary... what about Documentary? EDIT On second thought, that could be quite misleading. Commented Sep 16, 2015 at 17:32
  • 4
    I suggested "Knowledge Base" for the name; it maps pretty well to what we're trying to do here. Commented Sep 16, 2015 at 17:34
  • 1
    @ShotgunNinja The "Documentary" project is actually Meta (i.e. "Stack Overflow: The Making of") :)
    – duplode
    Commented Sep 16, 2015 at 17:37
  • 3
    Documentation Commentary... Documentary... how about Commentation? :P
    – gla3dr
    Commented Sep 16, 2015 at 17:39
  • I was going to suggest that as well, but that sounds just a touch too business-y, plus it collides with "comment", which implies short, continuous responses for clarification here on SO. The Documentation project's goal is pretty much the opposite of a comment: long, static, semi-authoritative articles serving as a collaboration between users past, present and future. Commented Sep 16, 2015 at 17:44
  • 5
    Maybe call it Community Docs? Dev Docs?
    – Becuzz
    Commented Sep 16, 2015 at 17:52
  • 9
    @Becuzz If it came to a vote, I'd vote for Community Docs. Dev Docs is too limiting and carries its own stigmas (Devs vs. Non-Devs). Commented Sep 16, 2015 at 17:55
  • 4
    I like the name "Community Docs", it's a kind of neutral name but it still describes everything it'll contain (examples, documentation, tutorials, ... made by the community) And because it's neutral (not related to programming only) I think it'll be more convenient to extend this to other stack exchange sites. Commented Sep 18, 2015 at 16:11
13

Can We Close Questions Against Documentation?

These Documentation example pages seem to take the form of an extensive, canonical answer regarding particular language features.

One thing that comes to my mind right away as an example is PHP's PDO. I could imagine an extensive PDO Documentation section, featuring basic usage and transitioning from the now-deprecated mysql_* functions.

If we have an exhaustive answer to this type of query that lives in Documentation, can we close questions against that documentation page? If not, I see an easy way to gain reputation points: copy/paste relevant sections from the Documentation examples, link to the Documentation page, and link to the official documentation. Now I've got a great answer that I didn't actually write and no one can call plagiarism.

8

Intro:

Start with Positives (and Meta for Meta!):

for (int i = 0; i < int.MaxValue; i++)
{
    Console.WriteLine("I Love SO");
}

I love SO...I love SO. I'm a self-taught programmer, and SO has been my loving, guiding, sometimes cruel tutor throughout the years. But I fear that you are taking too traditional of a route and missing a great opportunity for a "true" change to documentation.

I suggest that instead of having one "officialesque" topic, like Wikipedia does where there is one central document that is edited by multiple users, that you allow for more dynamic content "compositional viewing".

Analogy:

Wiki : Relational Database as Compositional Viewing : Event-Sourcing + DataMining

Don't be Wiki and try to make your interpretation of the data be the structure (I love wikis and relational databases, btw, not hating). Let people create raw data, and then event-source / data-mine that data into constructs that provide value.

Stackumentation:

Start with a central document, either an existing documentation page, an open-source code page (e.g. on GitHub), or a SO-generated page...maybe even just a SO question.

Then you have different people "mod" that page with wrapper-like stacks. These wrappers are where the "tags" are appended, and they specify what "flavor" of the "documentation", i.e. what technology "stack" they are using - Stackumentation!

Then, as a consumer of this "compositional document", I can "create" my documentation view by selecting filters of the who's and the what's: * Who is or isn't "reputable" or "someone I respect"
* Who is "my style coder"
* What technology(s) I'm interested in.
* What version(s) I'm interested in.
* What version(s) I'm specificaly not interested in.

Notes:

  • These would be on a per-document and a site-wide basis saved with the viewing user's profile.
  • Once a particular stack is upvoted enough, then it becomes an "officialesque" page.
  • These officialesque pages would then be googleable.
    • The cool thing about this is that when you google into one of the pages, you are inside
      of the stacks and can easily navigate/filter your way to other "pages" that are actually
      compositional views of the same/related pages.
  • This would address the issues of rep and avoid the necessity of a specialized review
    system that sounds more complicated than the existing awesome one that SO already implements.
    • People who get value out of something get to upvote on a per-topic and/or per-stack basis.
    • People can create crap that no one reads and it simply doesn't get upvoted or even gets downvoted.

Wrap-up:

At least that is the dream that I have...::sigh::

Whatever y'all come up with will be awesome, I am sure! I just had to post these thoughts, as SO + Documentation is something I have thought about and looked forward to for quite some time! I'd love to get into the philosophy of this, but I think this post is bigger than I need anyway...

Looking forward to the documentation!

13
  • This is an interesting idea but I'm having a hard time visualizing what exactly happens. How do I avoid reading the same content by different authors?
    – Josiah
    Commented Sep 22, 2015 at 19:05
  • The document that you read is like a competition of expression for whatever the inputs you give SO. Right now, the inputs are search box, up/down votes on questions, up/flag votes on comments. When you click an up vote, what happens? The thing becomes more visible, and thus has more prime real estate as far as attention is concerned. It is the same process. Think Adobe Photoshop Layers + Google Docs collaborations + SO gamification + Big Data/Event Sourcing. Only, instead of the "one" document, that is central, you are creating "views" of data, just like data mining raw data. I'll blog...
    – user4275029
    Commented Sep 23, 2015 at 11:45
  • 1
    @Josiah I've just completed a blog about the design ideas that will give you a visual on the concept. ibgib.com/index.php/… If you, or anyone else who is upvoting this, likes the post, then you may want to get some others to upvote this....we're waaaaaaaay down the page.
    – user4275029
    Commented Sep 24, 2015 at 14:23
  • @ibgib Your site is timing out for me, unfortunately. Commented Sep 25, 2015 at 21:24
  • @Maximillian It is slow but it shouldnt be timing out...hmmm. I'll try bumping up the azure vm temporarily.
    – user4275029
    Commented Sep 25, 2015 at 22:06
  • @ibgib I just tried loading it again. Time to first byte is about 12s, but after the wait most of it is loading fine. But the images embedded in your article are at https urls which are giving insecure responses (example), so the images aren't loading for me on Chrome. Hope that helps a bit! Commented Sep 25, 2015 at 22:15
  • @Maximillian Yes I just got the same on my phone...I'll fix it presently.
    – user4275029
    Commented Sep 25, 2015 at 22:17
  • @Maximillian Ive changed the links so it should be working (albeit slowly). Thanks for pointing it out!
    – user4275029
    Commented Sep 25, 2015 at 22:24
  • Btw, "stackumentation" is just a silly name...apparently it is downvoted to oblivion. But I still think its the right approach to a gamefied organic system. Anyway, Im sure whatever they make will be awesome.
    – user4275029
    Commented Sep 25, 2015 at 22:27
  • As to your Stackumentation, StackExchange uses tags well. Perhaps here, we have a strong tagging system with few "classify" entries (classify:tutorial + classify:reference on one doc entry, classify:principles only on another), then, language specific tagging (lang:python3 on python3 pages, lang:java on other pages). That way, your query can be, "I want a tutorial on python 3" and subsequent queries can be relative to that first filter.
    – maxpolk
    Commented Oct 2, 2015 at 16:39
  • I am not sure what this means, but it sounds wonderful! Commented Oct 2, 2015 at 21:40
  • @maxpolk Tags are definitely what I had in mind with the "stacks"! Though, it sounds to me that you still want to point someone to a "single" document (with possibly some edits by people) via a query and that is NOT what I'm talking about. I'm talking about a dynamically composable, mass group-collaboration, gamefied document rendering mechanism and I've shown in the blog post on how a possible UI could be implemented for it. Am I misunderstanding your approach, or are we saying the same thing?
    – user4275029
    Commented Oct 2, 2015 at 23:28
  • @PeterMortensen Thanks Peter! If you haven't already, you can check out my blog post at ibgib.com/index.php/… to better help you visualize what I'm saying. (Forgive me for having a slow site...patience is a virtue on a budget!)
    – user4275029
    Commented Oct 2, 2015 at 23:30
7

More of a comment than an answer, but this way people can up- and downvote this. Please do so.

I'd like to propose something for this issue (emphasize):

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.

I think an appropriate name would be "// TODO". I think it's within the spirit of the entire endeavour to pick up where others only left a

Documentation is mandatory. Somebody didn't do it or didn't do it sufficiently or in an easily consumable way. Maybe they were in good spirit to provide good documentation. Either way, the community needs more/better/... documentation.

So we shall not rest until every documentation related // TODO is purged from the code.

And maybe this will condition our future selves to be incapable of closing an editor with a pending // TODO for documentation.

7

How much of a time commitment are you looking for in private beta users? I'm considering joing the beta, but unfortunately, I will only be able to be a casual user at this point. I'd probably do a fair bit of reading and a little bit of posting, but I wouldn't spend hours participating in discussions, voting on moderators, adding content, and so forth.

Would it still be helpful for someone like me to join the private beta, or are you only looking for volunteers who will give a good chunk of their time?

7

Whilst answering How do we prevent pointless Documentation? you've mentioned that there will be sections for requested topics and documentation that needs improvement. I really like this part mainly because it should hopefully focus the documentation system. Those who intend (or are capable of) documenting will know what is needed and be able to use their time more efficiently.

However, you've mentioned that there will be a review system. I do think a system will be needed, but I'm particularly interested in how you plan for this to work. Will it work similarly to suggested edits in the current Q&A set up? Specifically, if a user under 2k reputation points edits a question or answer now it enters the Suggested Edit Review Queue and the edit button is disabled for other users. Will a similar model be in place for documentation?

In the early stages of documentation this may be of more concern than when it has matured and additions and updates are less frequent. I could see this being quite harmful to getting the community behind the idea of documentation unless additions and changes can be quickly reviewed and accepted. Another approach would be to allow simultaneous creation (and edits) of documentation, but then how would conflicts be merged together? Could this be another review task specifically for, say, Gold Tag badge holders?

Documentation is a very interesting proposal and I'm quite intrigued as to how you are going to make it work ;)

5
  • 1
    Having recommendations for documentation articles is a great way to improve the breadth of the system as well as provide documentors (or "warlords"?) with a chance at getting started with low-hanging fruit. Commented Sep 17, 2015 at 14:40
  • @ShotgunNinja Warlords has a nice ring to it. It's like we are fighting a war against ignorance :)
    – Keale
    Commented Sep 18, 2015 at 1:41
  • 1
    @Keale Having gone to actual war several times, this sort of hyperbole kind of annoys me. But I find that quite a few things around here annoy me these days, so whatever.
    – zxq9
    Commented Sep 18, 2015 at 2:58
  • I only said "warlords" because of the post title "Warlords of Documentation" above. Let's hope SO has the sense not to use such a term when this system goes live. Commented Sep 18, 2015 at 13:36
  • I just wanted to mention that the "simultaneous creation (and edits) of documentation" is covered in my answer. Anyone can create whatever documentation they want (or whatever regulations/restrictions that SO puts on this). Then, you can create filters for the existing documentation. For example, I like long, descriptive variable names, and I abhor 2- and 3-character names. Some people are the opposite. I could create a different view of someone else's documentation just using my variable names. Or a less trivial mod would be modding something that worked in v1 that now uses v2 member names.
    – user4275029
    Commented Sep 21, 2015 at 11:49
7

Regarding versioning: what about cases where version is not linear?

For example, here is what version information for .NET on MSDN looks like:

Will Stack Overflow documentation support something similar?

1
  • Totally agree. Actually, I think this point is a pretty crucial one. I just browsed the Java documentations a little bit, and found one doc where the author(s) added the single versions specifically (as links, like the list you pointed out). Sadly, this does not go in line with the 'tagging' solution (at least on that page, but this is a cosmetic doing I guess). On the other hand, something like a 'Java SE 1.0–Java SE 8' tag I've seen, tagging may be correct on the one hand, the information itself may be not specific enough on the other hand. How to deal with the single versions / variants?
    – bully
    Commented Jul 21, 2016 at 18:21
5

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.

Sooo basically literally exactly the problem originally posed is now being brushed off? The original thing was having autogenerated docs for a library having the list of methods with no documentation; that's what got me excited for this proposal.

Now I'm not so sure.


On another note; what about duplicate documentation altogether? Does it get deleted? Is it marked as a duplicate? What if one of the documents has good information? Are they merged? Won't too many duplicate pages kind of crap up the whole system, and re-create the problem we're already facing?


I want to be enthusiastic about this proposal, but I am going to err on the side of be pessimistic this time; I don't see much standing for, well... any of this.

3

When a new version is introduced, we’ll assume that anything on the previous version is still supported

Please make sure to have an option of

  • Introduced in 2.3
  • Deprecated in 3.0
  • Brought back in 3.1

Something along the above lines. I don't remember from the top of my head where I read this. But some libraries do this.

So basically make sure the version support can be edited later on with flexibility. The assumption that you are making may be completely wrong in some cases.

2

Regarding plagiarism, would it be possible(/permissable) to automatically hit Google with a few key phrases from someone's contribution and see if it's reproduced, word-for-word (or almost word-for-word), from another searchable site? At that point, the user could be prevented from posting the content, and warned that you really don't want them to copy/paste stuff from the Internet.

It's true that with a little effort someone could probably fool your algorithm into accepting a mostly-plagiarized post, but it would prevent the accidental "I'm new here" type of plagiarism, and open the door to real consequences for the few people who are obviously going out of their way to get around it.

0

How will you handle additions that are not yet implemented? It occurs often in ECMASCRIPT implementations—which is very annoying; you can have an existing interface missing the underlying implementation.

I propose to have 2 separate options:

  • added in x.x.x
  • implemented in x.x.x

Not the answer you're looking for? Browse other questions tagged .