Welcome to Stack Overflow Documentation
Together, we can do for Documentation what we did for Q&A.
How is Stack Overflow Documentation different?
When we reviewed traditional documentation, two things were clear:
It had to be based on assumptions, not need
It was usually written once, often by someone not even using the technology, so it was a guess at what to focus on.
It didn't prioritize good examples
People learn best when they can see things demonstrated in actual code.
We can do better. You can help.
Anyone can contribute
From whole new topics and examples to small copy tweaks, all improvements are welcome.
Documentation is licensed under the same terms as Q&A, allowing for widespread reuse.
Anyone can give feedback
If a topic or example is missing or incomplete, anyone can request new topics, request improvements, or downvote.
These requests are valuable feedback for the community, focusing future efforts.
What's different from Q&A?
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.
These resources haven't had a place on Stack Overflow, Documentation gives them a home.
If Q&A is chocolate, Documentation is peanut butter.
Two great tastes, better together.
-
Collaborative authoring
Drafts can be shared with others, and proposed changes can be commented upon. You can also invite other users working on the same material to collaborate in chat.
-
Anyone can contribute
All changes are reviewed by other users, and the full history is available to everyone, so you won't break anything.
-
No more broken links
Every topic link contains a timestamp, so if you need an older version you can always get to it.
-
Flexible versioning
A tag's first topic maintains a list of versions. These versions can be applied to whole topics or individual sections within the tag's documentation.
How is Documentation organized?
Documentation is divided up by its subject matter, the library, language, framework, etc. that developers are using. Practically all subjects have a tag on Stack Overflow's Q&A already, so we group Documentation by those tags.
Documentation for a tag - .net, say - is composed of topics which are groups of related examples, accompanied by optional prose. Things like "Arrays," "Extension Methods," "Maps," and "Higher Kinded Types".
Examples show how to accomplish a task or solve a common problem, and they have code more often than not. Good examples are broad and generally useful, remember that Q&A exists for very specific questions!
It's all about examples.
Examples illustrate common tasks or solutions to common problems - remember "Show, Don't Tell". A good example is self-contained and succinct, and more often than not contains code. It is more important that code in examples be illustrative and focused than that it be copy/paste-able; leave out boilerplate when it distracts from the concept the example is meant to illustrate.
Because our goal is to ensure developers always have great examples, topics can't be created without at least one example.
In addition to examples, a topic has some optional sections. These serve to make examples more succinct, by allowing for documentation of common parameters, syntax, and other remarks that would otherwise need to be duplicated between examples.
You decide how to make documentation most helpful.
Every edit to documentation goes through peer-review as a proposed change, so the answer to "Who decides what belongs in Documentation?" is, in a very real sense, "You do!".
As fellow developers, we naturally have some opinions ourselves,
Hit the high notes with examples
An example should be useful to lots of people. Don't try to be exhaustive and cover every conceivable use. Stack Overflow Q&A is available for very specific questions.
Keep example counts manageable
The typical topic has between one and six examples, and the typical example has a paragraph of explanation and some code. As topics grow, consider splitting them and moving examples to new topics.
Don't be too narrow
"Sorting" is probably a good topic for some tags. Having separate topics for "Sorting ascending" and "Sorting descending" is probably not ideal, since the key concepts for both will be the same.
Badges and Reputation are shared across Q&A and Documentation.
The existing Q&A reputation and badge systems have been extended to Documentation. You still have one number, your total reputation, which is a measure of how much you've helped your fellow developers.
There are a whole slew of Documentation specific badges to earn.
Reputation is earned by
- contributing to Documentation that is cited in answers
- contributing to examples that are upvoted
- having your changes reviewed and approved
You've already earned a Documentation badge:
Ready to help?
Hop in to one of these tags
|
C# Language
138 topics
|
Java Language
154 topics
|
