Thursday, March 24, 2016

How to write documentation



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

$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.rst
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/
Markdown是一种可以使用普通文本编辑器编写的标记语言,通过简单的标记语法,它可以使普通文本内容具有一定的格式。
Markdown具有一系列衍生版本,用于扩展Markdown的功能(如表格、脚注、内嵌HTML等等),这些功能原初的Markdown尚不具备,它们能让Markdown转换成更多的格式,例如LaTeX,Docbook。Markdown增强版中比较有名的有Markdown Extra、MultiMarkdown、 Maruku等。这些衍生版本要么基于工具,如Pandoc;要么基于网站,如GitHub和Wikipedia,在语法上基本兼容,但在一些语法和渲染效果上有改动。

Labels

Review (572) System Design (334) System Design - Review (198) Java (189) Coding (75) Interview-System Design (65) Interview (63) Book Notes (59) Coding - Review (59) to-do (45) Linux (43) Knowledge (39) Interview-Java (35) Knowledge - Review (32) Database (31) Design Patterns (31) Big Data (29) Product Architecture (28) MultiThread (27) Soft Skills (27) Concurrency (26) Cracking Code Interview (26) Miscs (25) Distributed (24) OOD Design (24) Google (23) Career (22) Interview - Review (21) Java - Code (21) Operating System (21) Interview Q&A (20) System Design - Practice (20) Tips (19) Algorithm (17) Company - Facebook (17) Security (17) How to Ace Interview (16) Brain Teaser (14) Linux - Shell (14) Redis (14) Testing (14) Tools (14) Code Quality (13) Search (13) Spark (13) Spring (13) Company - LinkedIn (12) How to (12) Interview-Database (12) Interview-Operating System (12) Solr (12) Architecture Principles (11) Resource (10) Amazon (9) Cache (9) Git (9) Interview - MultiThread (9) Scalability (9) Trouble Shooting (9) Web Dev (9) Architecture Model (8) Better Programmer (8) Cassandra (8) Company - Uber (8) Java67 (8) Math (8) OO Design principles (8) SOLID (8) Design (7) Interview Corner (7) JVM (7) Java Basics (7) Kafka (7) Mac (7) Machine Learning (7) NoSQL (7) C++ (6) Chrome (6) File System (6) Highscalability (6) How to Better (6) Network (6) Restful (6) CareerCup (5) Code Review (5) Hash (5) How to Interview (5) JDK Source Code (5) JavaScript (5) Leetcode (5) Must Known (5) Python (5)

Popular Posts