http://docs.writethedocs.org/writing/beginners-guide-to-docs/
https://github.com/writethedocs/docs/tree/master/docs/writing
http://blog.jobbole.com/98876/
You want people to use your code
If people don't know why your project exists,
they won't use it.
If people can't figure out how to install your code,
they won't use it.
If people can't figure out how to use your code,
they won't use it.
You want people to help out
You only get contributions after you have put in a lot of work.
You only get contributions after you have users.
You only get contributions after you have documentation.
Documentation also provides a platform for your first contributions. A lot of people have never contributed before, and documentation changes are a lot less scary than code changes. If you don't have documentation, you will miss out on a whole class of contributors.
It makes your code better
There is an old truth that writing things down helps you think. It's really easy to have an idea in your head that sounds perfect, but the act of putting words to paper requires a distillation of thought.
Writing documentation improves the design of your code. Talking through your API and design decisions on paper allows you to think about them in a more formalized way. A nice side effect is that it allows people to contribute code that follows your original intentions as well.
You want to be a better writer
The examples in this document are both valid Markdown and reStructuredText. reStructuredText is a bit harder to use,
Version controlled plain text
What to write
At first, you generally just need to appeal to two audiences:
Users
Developers
Users are people who simply want to use your code, and don't care how it works. Developers are people who want to contribute back to your code.
What problem your project solves
A small code example
A link to your code & issue tracker
Frequently Asked Questions (FAQ)
Your first steps in documentation should go into your README. Code hosting services will render your README into HTML automatically if you provide the proper extension. It is also the first interaction that most users will have with your project. So having a solid README will serve your project well.
A lot of people have the same problems. If things happen all the time, you should probably fix your documentation or the code, so that the problems go away. However, there are always questions that get asked about your project, things that can't be changed, etc. Document those, and keep it up to date. FAQs are generally out of date, but when done well, they are a golden resource.
How to get support
Information for people who want to contribute back
People usually have standards for how they expect things to be done in their projects. You should document these so that if people write code, they can do things in the norm of the project.
Installation instructions
Your project's license
Template
Include documentation in production workflow
Add it to the definition of done (see scrum development method [1])
Package and release documentation with code
A problem in documentation is called a bug, as any problem in code
Changes in documentation can be prioritized as any feature
A new version of documentation implies a new version of the product.
Synchronize code and documentation
https://github.com/writethedocs/docs/blob/master/docs/writing/documentation-usage.rst
Reference
Users trust documentation. They use it when they are not sure, to apply some recipe or best practice, to solve discussions, etc.
Remember, find
Users naturally search the documentation for content they can't remember. Search is a very important feature.
Share "non productive" content
Some content cannot be stored in scripts, configuration or other "productive" tools. Vision or conventions can be written in documentation.
Durability
Redirection
As an entry point, documentation is a good place to redirect users to other services or resources. What can't be maintained in documentation is referenced in documentation with hyperlinks or other straightforward redirections.
Keep it simple & straightforward
http://game-lab.org/posts/review-editing/
https://github.com/writethedocs/docs/tree/master/docs/writing
http://blog.jobbole.com/98876/
You want people to use your code
If people don't know why your project exists,
they won't use it.
If people can't figure out how to install your code,
they won't use it.
If people can't figure out how to use your code,
they won't use it.
You want people to help out
You only get contributions after you have put in a lot of work.
You only get contributions after you have users.
You only get contributions after you have documentation.
Documentation also provides a platform for your first contributions. A lot of people have never contributed before, and documentation changes are a lot less scary than code changes. If you don't have documentation, you will miss out on a whole class of contributors.
It makes your code better
There is an old truth that writing things down helps you think. It's really easy to have an idea in your head that sounds perfect, but the act of putting words to paper requires a distillation of thought.
Writing documentation improves the design of your code. Talking through your API and design decisions on paper allows you to think about them in a more formalized way. A nice side effect is that it allows people to contribute code that follows your original intentions as well.
You want to be a better writer
The examples in this document are both valid Markdown and reStructuredText. reStructuredText is a bit harder to use,
Version controlled plain text
What to write
At first, you generally just need to appeal to two audiences:
Users
Developers
Users are people who simply want to use your code, and don't care how it works. Developers are people who want to contribute back to your code.
What problem your project solves
A small code example
A link to your code & issue tracker
Frequently Asked Questions (FAQ)
Your first steps in documentation should go into your README. Code hosting services will render your README into HTML automatically if you provide the proper extension. It is also the first interaction that most users will have with your project. So having a solid README will serve your project well.
A lot of people have the same problems. If things happen all the time, you should probably fix your documentation or the code, so that the problems go away. However, there are always questions that get asked about your project, things that can't be changed, etc. Document those, and keep it up to date. FAQs are generally out of date, but when done well, they are a golden resource.
How to get support
Information for people who want to contribute back
People usually have standards for how they expect things to be done in their projects. You should document these so that if people write code, they can do things in the norm of the project.
Installation instructions
Your project's license
Template
$project
========
$project will solve your problem of where to start with documentation,
by providing a basic explanation of how to do it easily.
Look how easy it is to use:
import project
# Get your stuff done
project.do_stuff()
Features
--------
- Be awesome
- Make things faster
Installation
------------
Install $project by running:
install project
Contribute
----------
- Issue Tracker: github.com/$project/$project/issues
- Source Code: github.com/$project/$project
Support
-------
If you are having issues, please let us know.
We have a mailing list located at: project@google-groups.com
License
-------
The project is licensed under the BSD license.
https://github.com/writethedocs/docs/blob/master/docs/writing/documentation-is-part-of-the-product.rstInclude documentation in production workflow
Add it to the definition of done (see scrum development method [1])
Package and release documentation with code
A problem in documentation is called a bug, as any problem in code
Changes in documentation can be prioritized as any feature
A new version of documentation implies a new version of the product.
Synchronize code and documentation
https://github.com/writethedocs/docs/blob/master/docs/writing/documentation-usage.rst
Reference
Users trust documentation. They use it when they are not sure, to apply some recipe or best practice, to solve discussions, etc.
Remember, find
Users naturally search the documentation for content they can't remember. Search is a very important feature.
Share "non productive" content
Some content cannot be stored in scripts, configuration or other "productive" tools. Vision or conventions can be written in documentation.
Durability
Redirection
As an entry point, documentation is a good place to redirect users to other services or resources. What can't be maintained in documentation is referenced in documentation with hyperlinks or other straightforward redirections.
Keep it simple & straightforward
Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。
Markdown具有一系列衍生版本，用于扩展Markdown的功能（如表格、脚注、内嵌HTML等等），这些功能原初的Markdown尚不具备，它们能让Markdown转换成更多的格式，例如LaTeX，Docbook。Markdown增强版中比较有名的有Markdown Extra、MultiMarkdown、 Maruku等。这些衍生版本要么基于工具，如Pandoc；要么基于网站，如GitHub和Wikipedia，在语法上基本兼容，但在一些语法和渲染效果上有改动。
