30

Every site of the StackExchange network has the two following entries in their help-center*:

  • What topics can I ask about here?
  • What types of questions should I avoid asking?

I think something similar should be done for documentation. The three following question should be answered by the help-center or any other (official) resource:

  1. What kind of topic can/should I document? Should I really document an API that's currently in beta? Or should I wait till its officially released? Should I document something that's proposed for language addition, but not yet usable, which might even get dropped?

    This is important to tell the users that their topic is actually fine.

  2. What types of topics should I avoid to document? Should I document "Hello world with singletons", if there is already a normal "Hello World" and a "Singletons" topic? Should I document things that are considered worst practice?

    Or should I even document "hello world"? After all, that's usually just basic syntax together with a puts-like function, which could be documented instead. But maybe there isn't a puts (basic console output) topic, because no one seemed that it was documentation worthy (see above), so I do it anyway?

    Note that the current documentation has a point "Good examples", but not "Good topics", which makes it hard to know when a topic shouldn't get requested/created at all.

  3. What should be in the scope of a single topic? Using the example above, should I even request "Hello World with Singletons"? After all, that would put two independent topics into a single one, where each is understandable without the other. Alternatively, one could also call this question "When is a topic too broad"? If there are 200 upvoted examples for a single topic, it's either very versatile, or rather too large.

In my opinion those three questions are essential to the success of SOdocumentation.

They're all in a single question, since any answer on one of them also answers the other two to a high degree.

* well, at least as far as I know all Q&A parts, e.g. not Career.

7
  • 10
    Agree, there is no Stack Overflow Documentation Documentation!!
    – EKons
    Jul 21, 2016 at 12:29
  • 3
    Also: How abstract should topics be? Eg., there is currently a proposal for functional programming; I would be inclined to contribute to this, but I'm not sure whether pure "concepts" are supposed to be documented, as opposed to concrete languages/APIs. I can see a similar case for other things like "recursion", "patterns", etc. Jul 22, 2016 at 8:19
  • 1
    @phg The problem is that in a example-driven approach, there will be concepts whose examples differ highly between several languages. And even if they don't differ too much (conceptionally), this can and will lead to language wars in the examples. Things like this prevent me from writing any example at all.
    – Zeta
    Jul 22, 2016 at 8:56
  • I agree. My problem is that there are some tags that are essentially intersections of other tags and could in principle be handled in those, while it would also make sense to describe their concepts abstractly -- think of lambda calculus vs. anonymous functions in different languages, or patterns and their implementations. And I don't know what is expected in such a case. Jul 22, 2016 at 10:28
  • 1
    I also noted that the tour for documentation lists as examplary topics for .NET "things like 'Arrays,' 'Extension Methods,' 'Maps,' and 'Higher Kinded Types'" -- so, does that mean that every explanation of "concepts" should be bound to one language/technology...? I think that's a rather important decision to be made now. Jul 22, 2016 at 10:30
  • @phg Yes. But there are almost no official decision, except that documentation should be example based and that those example should be awesome (aka upvoted examples rise to the top). tw you'll probably also want to comment on this meta topic.
    – Zeta
    Jul 22, 2016 at 10:40
  • Let's answer them right here. faq-proposed.
    – jscs
    Jul 24, 2016 at 19:23

1 Answer 1

5

In true FAQ (-proposed) spirit, I am making this CW. Feel free to edit, especially since this is a highly volatile topic and likely to change.

Be Educated

Before anything, read the Documentations tour and earn the educated badge.

What tags are good for Documentation?

You only need a score of 1 in a tag in order to propose and vote for its documentation. Unfortunately, many tags are not a good fit for this format (and many more are just bad tags).

A good (and eligible) tag for documentation will:

  • Refer to one specific language or technology
  • Have at least 10 people willing to participate in creating its Documentation page.
  • Have at least 500 questions using the tag.) To see how many questions use a tag, use the tag search
  • This restriction will likely change after it's out of Beta, since now the focus is on getting the big topics documented.

How Should Documentation be Organized?

This goes hand-in-hand with what topics are good for Documentation, and what Examples should contain. Organization is very important (although many topics are severely lacking it currently).

The tour says:

Documentation is broad, and it is a general reference. You aren't documenting a specific problem you're facing, you're helping others deal with an entire class of problems by documenting.

Documentation should apply to a broad audience. Of course, the most obvious thing would be the type of content found in tutorials, but this information is already covered in other places. The most significant contributions will cover entire classes of problems.

I feel my metaphor explains it very well:

These problems are headaches.

If you go to Health.SE, and ask "how to fix my headache", it will get closed as too broad, since there are a lot of things that cause headaches. And there are different types of headaches, too.

But "Fixing Headaches" would be a good topic for Documentation. Headaches affect almost 50% of the population, so it's certainly not too localized of a problem.

The broad nature also means that organization must dictate the structure of the Documentation. (And understanding the organization is important to understanding why this type of problem can be effectively covered in Docs.)

I would start out with a section that explains the different types of headaches, and how one can go about troubleshooting to figure out which one they have (Where does it hurt?). That section would include links to sections that help narrow the source of the headache to its source. Did you get wasted last night? You likely have a hangover. That, in turn, can be linked to another page on Docs that explains how to fix headaches caused by that particular source.

How should Examples be used?

Under a tag, there are topics. Each topic has examples (and may also have additional sections). Each example is made of its own title and a body.

The title of the Example should describe its contents. So, if the title is "Rotating Images" it should only describe how to rotate images. The explanation for how to scale images belongs in its own example, under the title "Scaling Images". Avoid stuffing too much into one example.


There's also some solid information in the official announcement... hidden at the very bottom of the page. For ease of reference, I have copied the relevant part:

What can be documented?

  • We're thinking "anything you use through code" as a really rough guideline, but we'll ultimately decide together as a community, just like with what’s on-topic for Q&A.
  • For the betas, we're planning to restrict ourselves to established and widely used projects. We're trying to test out the bigger stuff first, to make sure all the tools and processes can cope. If all goes well, eventually just about anything that sees some Q&A activity will be fair game to document.

What should be documented?

  • Anything where we can actually make it better. If a project already has awesome documentation that's easy to search and cite, then there's no need to duplicate it on Stack Overflow. We're interested in fixing what's broken with documentation, not just moving them onto Stack Overflow.

What's the line between a Question and a request for a Topic?

  • Topics are broader in scope than Questions. In fact, we're expecting that if you "asked" most requests, they’d be closed as Too Broad.
  • Topics should also have multiple Examples, so a request that can be served by a Topic with a single Example (ie. one block of code) is probably too narrow.

Is importing existing documentation encouraged?

  • No. We're hoping we can improve documentation, not just move it under the stackoverflow.com domain.

What license will documentation be under?

5
  • I'm not sure if this is worthy of inclusion in this answer, but I've created a query on Data.SE which allows you to see if a tag has at least 500 questions using the tag. If you enter % for the tag name, it will show all tags which meet that criteria. Jul 28, 2016 at 14:40
  • @MikeMcCaughan Why not just do a search for [tag] is:q and see if the number is greater than 500?
    – Laurel
    Jul 28, 2016 at 16:16
  • You could do that, but this also lets you find all tags that have > 500. Jul 28, 2016 at 16:18
  • @MikeMcCaughan True, but you can also just browse the tag list. Anything past page 147 doesn't have enough questions. Actually, browsing the tag list is probably a better than searching to get the number for specific tags, too.
    – Laurel
    Jul 28, 2016 at 16:24
  • 1
    Fair enough. I like that I didn't need to go through 140+ pages, but to each one's own :). Jul 28, 2016 at 16:29

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