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?