Given the barrage of downvotes because I could not find something on meta that apparently everyone thought I should know, I would like to mention what I see is a serious disconnect in the organization of documentation on SO from what is intuitive.

First, the only form of documentation on SO is a FAQ. FAQ as the sole form of documentation is sorely inadequate. Q&A (of which a FAQ is variant) is not the same as a book and one form cannot replace the other. Wikis for example, are not laid out in a Q&A fashion. SO really needs a site that outlines, for example the current rules (and all the rules) with respect to Reputation. There are many questions on meta about reputation but the algorithm has evolved over time and there is no easy place to get that answer. Similarly, getting to information on bounties is really buried which brings me to my next point.

The usability of the FAQ is awful unless your question solely relates to the 15 questions they list. For example, let's say you are trying to determine when a bounty is subtracted from your reputation (the question whose answer everyone thought I should know). Go to the SO FAQ page and notice there is nothing on the right panel of questions related to bounties. Do a search, in your browser, for "bounty". Nothing, go fish. Under questions? Go fish. Under reputation? Go fish. What if I don't get a good answer? Huzah! However, there is nothing that indicates that the moment the bounty is opened that the bounty amount is subtracted from their reputation (only that it eventually will be subtracted). Now the user has to go to fish on meta. That brings me to the third point.

It is counter-intuitive to be required to navigate to an entirely different site for documentation on the site you left. Most people assume meta is for people asking questions about designing a SE site not general questions that they would have found in documentation had it existed in a Wiki form.

Meta does not work well IMO as documentation nor is it designed to be that. It is designed as Q&A. However, many questions could be avoided if there was an actual documentation store like a wiki (Not a FAQ. Not Q&A). One reason for that is that questions are asked over time and the "right" answer changes over time (e.g. Reputation algorithm, daily cap algorithm). It is cumbersome to find the last "correct" answer.

So, SO really needs a wiki and more importantly they need to keep it current so that it is versioned along with the site.

  • 14
    I can't really disagree with the man... +1 – Pekka May 8 '12 at 21:23
  • 5
    What are your plans for the wiki to not also become a morass like you say the FAQ is now? – random May 8 '12 at 21:24
  • 1
    @random - A fair question. The documentation should be based on how the site actually works and thus only the people that can alter how the site works should be updating it. – Thomas May 8 '12 at 21:26
  • 9
    SE does not have anyone willing to keep the documentation up to date and they're even being paid. The community stepped up and that's why you have the FAQ. – random May 8 '12 at 21:28
  • 7
    Maybe SE needs to start paying someone to do the documentation then? I've been thinking that for a long time. – Pekka May 8 '12 at 21:31
  • 1
    I would think that documentation would be an avenue to improve the questions on meta by reducing the odds (not eliminating of course) of them being asked in the first place. – Thomas May 8 '12 at 21:34
  • 21
    Your belief that people read even a well formatted document is laudable, but experience and the horrors of Meta prove it's misguided – random May 8 '12 at 21:37
  • 2
    @random At least you would have a clear document/location to slap them over the head with if they ask something answered there. This instead of a random, hard to find earlier asked question not part of the current FAQ. – Bart May 8 '12 at 21:44
  • 14
    @random you're right, there will always be a huge audience who will not read anything they're presented. But there is a minority that is really willing to look stuff up. You have to admit they are given a very imperfect place for that - Meta. Meta may be a substitute for proper documentation for us veterans, but it's not for someone new to the system. – Pekka May 8 '12 at 21:59
  • 3
    Documenting everything that happens on an SE site would be a huuuuge wiki. Even wikipedia's own documentation is actually fairly difficult to navigate. Hell, just look at their getting started page. It's a sea of blue links and it's really hard to find your relevant info. I find it hard to believe any SE wiki would be easier to read than the current FAQ, but it sure would be a lot harder to impliment and a much bigger context shift. – Ben Brocka May 9 '12 at 1:09
  • 3
    @Pekka I'd have to be convinced this was actually a wide-spread issue before I could see putting resources behind it, personally. The only failing of the FAQ entry in this particular case is that it doesn't use the word "immediately" in the description, requiring you to visit the privileges page to find that out. There's probably some issue with all of the entries being collapsed (and thus unsearchable) by default, but the bounty dialog does have a "learn more..." link that takes you right to the appropriate section. – Tim Stone May 9 '12 at 1:23
  • 1
    The FAQ on meta has most of it – Ephraim May 9 '12 at 1:38
  • 2
    Honestly, it seems the entirety of your argument is based around you not finding one bit of information about bounties. That's really not a good reason to make earth-shattering changes. it's also something extremely easy to learn by doing, and not nearly catastrophic for the user. – Ben Brocka May 9 '12 at 2:04
  • 3
    @Ephraim - The key is on meta. I bet you that most SO users have no idea what "meta" is or they think it's about design and not help about using SO. While I'm find with meta being about discussions for how SO should work, SO should wholly contain its own documentation about how to use its site. Why isn't there a "meta meta" for how to use the meta.stackoverflow site? Clearly, some of the information and perhaps what I'm seeking is what many others seek which is a different way getting to that info. – Thomas May 9 '12 at 2:41
  • 1
    @Thomas Because it would make the main FAQ like 500 pages long. The main FAQ is for brand-new users who have questions like "how does rep work", not for detailed breakdowns of everything that can happen. Until SEI actually hires someone whose sole job is documentation, let's not shut off the only form of documentation that currently exists because you had trouble finding something. Make it easier to search, link to it from the main FAQ, whatever; but let's not get rid of it entirely in favor of an idealized system where the docs are always up to date and all information is found without effort – Michael Mrozek May 9 '12 at 15:28

A great many features of the site are unlocked via privileges -- and the best documentation of those features is often the descriptions there. For example, under the set bounties privilege you'll find the following text block:

What happens when I place a bounty?

  • The question is immediately bumped to the top of the active question list.
  • The question gets placed in the home page's featured tab for seven days.
  • The reputation you're using for the bounty is immediately and irreversibly deducted from your reputation.
  • If your new reputation brings you below the requirement for any privileges, you will lose access to those privileges.

(I have made bold the portion you were curious about, simply to follow the example.)

The main difficulty is where to find the list of privileges -- it is hidden inside a mouse-over drop-down box that shows when you hover your mouse pointer over your username in the header (or click the little triangle next to your username):

location of the privileges link

Perhaps this list of privileges could be made more prominent.

I think I've only found one instance when the documentation in the privileges section was not corrected for a recent change -- by and large, this documentation is kept up-to-date.

| improve this answer | |
  • The bounty privileges page is actually linked from the FAQ entry that the dialog used to start a bounty links to, even. I suppose it could save a click by being a bit more explicit about the immediate reputation deduction in the FAQ entry itself, by inserting "immediately" into "you will always give up the amount of reputation specified in the bounty". – Tim Stone May 9 '12 at 1:03
  • 1
    I didn't even know this existed, so thanks! I agree this could be made more prominent- perhaps a big flashing anigif on the FAQ leading to the priviliges page? (Or you know, just a hyperlink) – Robotnik May 9 '12 at 1:07
  • 2
    Been using SO for a couple of years now, I had no idea that from privileges were extended documentation such as this. Wouldn't have ever thought to look there and as far as I know, the search on the site won't crawl these pages. In the FAQ section on bounties, there is no link to this page. – Thomas May 9 '12 at 1:07
  • There is however a link in the section on reputation. Still, nice to know there is another area with some documentation even if it is well hidden. – Thomas May 9 '12 at 1:08
  • @Thomas There is a link to the privileges page with bounty information in the bounty FAQ entry. It's the one with the text "offering a bounty" (second paragraph). – Tim Stone May 9 '12 at 1:09
  • @TimStone - I don't see a link the bounty entry. The only link I see to privileges in the Reputation section. – Thomas May 9 '12 at 1:11
  • @Thomas these privileged pages are shown to you via a notification bar message immediately after you unlock them now. – Ben Brocka May 9 '12 at 1:11
  • 6
    Jeff Atwood calls this "Just-in-Time Documentation;" providing the user with only the information they need, when they need it. I am a huge fan. People won't read a manual, but they'll read a small bit of text at the time a new feature appears. – user102937 May 9 '12 at 1:11
  • @Ben, yeah, but most people won't post a bounty the day they get the privilege... – sarnold May 9 '12 at 1:12
  • @TimStone - OIC. Sorry. You have to go through "offering a bounty" which takes you to meta (which I also discussed. Shouldn't have to navigate way from SO for documentation on SO). – Thomas May 9 '12 at 1:12
  • 1
    @Robert: You never laid awake in bed at night with a large manual for some new toy that you really wanted to know all about? :) – sarnold May 9 '12 at 1:13
  • @BenBrocka - Would never (didn't actually) have thought to look at privileges to find help on bounties. – Thomas May 9 '12 at 1:13
  • 2
    @RobertHarvey - The problem with JIT documentation is that you have to outguess the user as to the subject which they seek. IMO, it is not a replacement for a real wiki which can be search and isn't Q&A. – Thomas May 9 '12 at 1:15
  • 1
    @RobertHarvey - Which many users do. The solution isn't to only provide JIT help. The solution is to provide both. Do you only learn by using Google or do you read books too? The former is the equivalent of searching meta. A wiki is the equivalent of the latter. Where I can use the Table of Contents or Index to find the material I want. – Thomas May 9 '12 at 1:18
  • 5
    Just In Time documentation is great, but it can take you only so far. It can't satisfy deeper interest in how the system works, or edge cases / problems. – Pekka May 10 '12 at 21:22

How Stack Exchange is currently documented.

Help Center

As of June, 2013, all sites have high-level documentation created and maintained by Stack Exchange employees. The goal of this documentation is to be:

  1. Clear
  2. Up-to-date

However it does not make any claims at completeness. Help pages mostly cover common situations or explain how features work in broad strokes. So, you'll find a list of badges and a summary of how to earn them. But it's not the right place to find the nitty gritty details, which are subject to change.

Meta Stack Exchange

As of April, 2014, questions applicable to all Stack Exchange sites may be asked and answered right here, on Meta Stack Exchange. (Before that date, Meta Stack Overflow served the same purpose.) We also encourage users to use per-site metas to document issues specific to individual sites. (Note: users are also free to ask about network-wide issues because we think of individual sites as separate communities.) The goal of Meta to be:

  1. Comprehensive
  2. Clear

So people are encouraged to ask about edge cases they run into, obscure bugs, and help with nuanced use of our features. Our developers keep an eye on questions. Many features are developed with input from questions. Site policies often begin with questions. Just like our main Q&A sites, meta sites do a pretty good job of providing clear, concise answers to even the most long-tail of questions.

Editing is encouraged if you discover a mistake or outdated information. But there's a lot of historical information that never gets updated. (Remember the orange bar?) We have tools such as duplicate closures, sidebar links, and the meta FAQ question that reduce confusion to a degree. Even so, everytime a developer changes some code there's a chance information on meta will go out of date.

JIT Help

We make heavy use of documentation embedded in our user interface, which is often referred to as JIT documentation. Like our help center, these bits of documentation are intended to be clear and up-to-date. They also give us the rare opportunity to include details that the user needs right at that moment. Most people won't care that Stack Exchange OpenID restricts users from using their email as a password. But for those few who try it, we let them know right then and there:

JIT help

Chat, comments, blogs, podcasts, developer talks, email, etc. and so on

Finally, we have about a dozen other places to disseminate information. We strive for clarity and accuracy, but not every medium affords the same level of each. As much as I love our podcasts, it can often be difficult to figure out which bits are jokes, which are wild speculations that will never see the light of day, and which are items that people should pay attention to. Our blog posts tend to be more clear (I hope!) but we don't do much to keep them up-to-date. (Well, other than ones we cite all the time.) Chat items and comments become obsolete. At best outdated comments will get deleted. You'll just have to use your common sense with these miscellaneous channels.

Why do we have all these channels? Every month, we have company-wide meeting with a standard set of announcements. One of them is "Default Public", which means "Unless there's a good reason not to, we should be saying and doing things in public". We fall short of that goal often, but nearly every day someone will say something like "Shouldn't that be a meta post ... or something?"

The Mythical Man Month is still worth reading

The Mythical Man Month concludes with a chapter called "The Other Face" that explains how to write documentation for users. I want to summarize every single point in that chapter, but you can read it yourself. I will use that chapter to set up an association between traditional software documentation and our documentation:

  • Map of the forest: the tour page
  • How to use Stack Exchange: the help center
  • Detailed test cases: meta
  • Flow charts: we don't have those
  • Self-documenting programs: tool-tips, badges, pop ups, banners, notifications, user profiles, et al.

For those who are wondering about the missing comprehensive, "here's how every part works in detail" documentation, I strongly suggest you read "The Flow-Chart Curse" section in Fred Brooks' book. That said, I think there might be room for a wiki that fills any gaps between the help center and meta. I'm worried, however, that a wiki would try to fill the flow chart gap, which would largely be a waste.

| improve this answer | |

So, SO really needs a wiki and more importantly they need to keep it current so that it is versioned along with the site.

SO does not need a wiki. The information (more or less) exists; what SO needs is better cataloging of that information. JIT-style documentation is nice, but only if you're about to use it right then. If you need to look something up, it's a lot less user-friendly because there is no other alternative.

| improve this answer | |
  • you could build a proper catalog in the faq tag wiki, if it becomes awesome we can promote it better – waffles May 11 '12 at 3:01
  • 2
    @waffles - That would requires users A. know to go to meta and B. know to search for the FAQ tag. Neither of those are intuitive. – Thomas May 11 '12 at 15:21
  • 1
    + 1 I would agree that a better organization of the existing information placed on SO would work. That information should include the official, current rules (as opposed to best answer) on the daily cap algorithm, the rep effect of down votes (which has changed over time), the consolidated list of items that effect reputation etc. – Thomas May 11 '12 at 15:22

I started something a long time ago on WikiBooks:

http://en.wikibooks.org/wiki/The_StackExchange_User_Guide (yes, I know - there is supposed to be a space between "Stack" and "Exchange")

Perhaps we could encourage the community to start adding some more content?

| improve this answer | |
  • Figure out how to give points for edits... – sarnold May 18 '12 at 1:50

Personally I don't feel we need a catalog that encompasses every nuance of the system. People hate reading big books, what they want is answers to specific questions.

We try hard to give you "just in time" documentation, though we can do a better job refining the system. When you get a new badge, we tell you why you got it and what it means. When you get a privilege, we tell you what it is and what it implies. When you run out of votes we let you know what your daily limit is, and so on.

Take your bounty example, when you click "start a bounty", you are presented with the text:

offer [50] of my own reputation for an answer to this question

There is even a link to more information. This can really only be interpreted in one way.

Now, if you are afraid to click "start a bounty" cause you think something disastrous is going to happen, and really think it should be "start a bounty..." instead, it is a topic for a separate discussion (so we can address it by itself)

Similarly, if you think that 1 rep users should still see the link, it is a subject for another discussion.

Another couple of concrete improvements I think could help in this area are "duplicate handling" and "improved search". Both are on our roadmap.

I am not against improving "tag wikis" and perhaps the "tags" page on meta or sidebar, but I think we need to focus on small concrete changes here.

| improve this answer | |
  • "Now, if you are afraid to click 'start a bounty' cause..." What if you don't click that button because it doesn't make sense to you that the way to learn about how bounties work is to try to make one? It's not a question of fear; it's a question of, "it never occurred to me." In general, documentation is not found by trying to do something; it's found by looking for documentation. JIT documentation only works when you are actively trying to do something. If you're just looking for information (perhaps in preparation for doing something), it doesn't work. – Nicol Bolas May 11 '12 at 2:54
  • @NicolBolas in that case we could change it to "start a bounty (learn more)" for people with a small amount of rep – waffles May 11 '12 at 2:57
  • That still misses the point. I wouldn't necessarily even be looking at a question when I think "I want to learn about bounties." – Nicol Bolas May 11 '12 at 2:59
  • @NicolBolas People are probably going to be looking for information about how bounties work when they a) see a bounty offered, or b) want to offer a bounty themselves. In both of these cases they'll be given hyperlinks to more information about bounties. I don't imagine people will be unable to sleep wondering about how SO bounties work unless they either see a bounty or want to create a bounty. – Kirk Broadhurst May 11 '12 at 4:28
  • @KirkBroadhurst: How will we know if they're thinking about offering a bounty? It's not like that link will just magic itself into their brain when they are wondering about offering a bounty. Again, the may not be looking at the question at the moment. When I think "find info on X", my first thought doesn't go to "press the button to cause X to happen." My first thought goes to the upper-right area of the screen. It's useful to tell people how a system works when you're about to use it, but it's also useful for people to find that information when they're looking for it. – Nicol Bolas May 11 '12 at 4:45
  • 3
    "people hate reading big books" - speak for yourself please – dbjohn May 11 '12 at 19:48

You must log in to answer this question.

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