How to write technical documents in a novice programmer's Guide

Why do I have to write a document?

You'll be using your code in 6 months.

I find it more appealing to start by explaining the problem from a self-interested perspective. The best reason to write a document is that you will use your code in 6 months. The code you wrote 6 months ago is usually no different from someone else's code. You will be reading your code with a familiar feeling. Then a bad omen creeps in, and you find that the person who writes the code has no experience and no wisdom.

Once you've read the code that was easy to understand or tricky a few months ago, you'll start to sympathize with your users. As long as I write down why I want to do this, life will be so simple. The document allows you to record why the code is written like this. Similarly, code comments explain why, rather than how, the documentation is the same.

You want people to use your code.

You've written a piece of code and released it. You do it because you think others might find it useful. However, people need to know why your code might be useful to them before deciding to use it. Documents can tell people that this project is useful to them.

If people don't know the meaning of your project, they won't use it.

If people don't know how to install your program, they won't use it.

If people don't know how to use your code, they won't use it.

Only a handful of people will delve into your code and use it. Few people will use your code unless it has good documentation. If you really love your project, write it to a document and let others use it.

You need someone else's help.

Open source projects are magical, right? You publish the code, and then the code gnomes comes in and makes you better.

There is a wonderful feeling when you release the code. It comes in all sorts of ways, but it always gets you excited. Someone's using my code? It's a mixture of fear and excitement.

I have created value!

What if it goes wrong?!

I am an open source project developer!

God, someone else is using my code ...

A written document can lessen this fear. A lot of fear comes from creating things for the world. My favorite quotations on this subject are as follows:

Fear comes from the important things you do.

If you're doing something that doesn't scare you, it's not going to benefit you or the world.

Congratulations, you're scared! It means you're doing something important.

Actually, that's not exactly the case.

Open source projects are really surprising, but they also have to conform to the rules of the real world. You have to pay to gain.

After you have paid a lot of work for the project, you will be able to contribute.

After you have users in your project, you can get a contribution.

After your project has a document, you can get a contribution.

The documentation also provides a platform for your first contribution to your project. Many people have never contributed to open source projects, making it much scarier to modify the code than to modify the document. If you do not have a document, you will lose this type of document contributor.

Documents make your code better.

There is an old fact: writing things down helps you think better. It is easy to have an idea that sounds good in your mind, but to write your thoughts down on paper requires a sublimation of your mind.

Writing a document can improve the design of your code. Discussing your API and design decisions on paper allows you to think about them in a more formal way. It also has a good side effect: let someone else contribute the code to your original intent.

You want to be a better writer.

Writing a document is different from the way most people experience writing. Technical writing is an art that is not innate. Writing a document will be the starting point for you to become a better technology writer, and as a programmer, this is a useful skill.

Writing can become easier as time goes by. If you haven't written for months, it will be more difficult to write again. Writing a document while doing the project will keep you in a reasonable rhythm.

What tools to write with

A simple beginning is the best way to achieve real results. I will provide a smooth road for you to go, after you have the basic idea, you can expand the scope. These tools are powerful and easy to use. This will remove the barriers to writing.

The examples in this article are valid in both Markdown and Restructuredtext. Restructuredtext is a bit hard to use, but more powerful. I recommend you to look at all two, and then decide which one you want to use.

Plain Text version control

As programmers in the world of plain text in our lives. Our documentation tools should not be an exception. We want a tool that converts plain text into beautiful HTML. We also have some of the best tools for tracking file changes. Why do we give up using these tools when we write documents? This workflow is powerful and familiar to developers.

Basic examples

Resources

---------

* Online documentation:http://docs.writethedocs.org/

* conference:http://conf.writethedocs.org/

The above text will be rendered as a title, with a list below. URLs will be automatically hyperlinked. This is easy to write, not only meaningful as plain text, but also nicely rendered into HTML.

Readme

The first document you should write is the README. If you provide the appropriate extension, the code hosting service will automatically render your README as HTML. It is also the first time that most users interact with your project. Therefore, a reliable README is very useful for your project.

Some people even start the project from the README.

What does the document write

Now let's talk about the important things. Make sure your users get all the information they need, but not too much.

First, you need to ask yourself: for whom the document is written. In the beginning, you just need to attract two types of readers:

User

Developers

Users are people who just want to use your code, regardless of how it works. Developers are people who want to make a contribution to your code.

What problems did your project solve?

Many people will find out what your project is through your documents. Someone would mention it, and someone would randomly search for a phrase with Google. You should explain what your project does and what it means to exist. Fabric is doing well in this area.

A small example of a code

Provide a vivid example of what your project will normally be used for. Requests is a good example.

A link to code and problem tracking

People sometimes like to browse the source code. They might be interested in archiving the code bugs they found. It is easy to make it easier for those who want to contribute to the project as much as possible. I think the Python Guide is doing well because it has links to parts of the code.

FAQ (FAQ)

Many people will have the same problem. If the problem continues to occur, you should modify your document or code appropriately to solve the problem. But there are always questions about the project, things that can't be changed, etc. that are often asked. Keep these records in the document and make them up-to-date. FAQs are usually obsolete, but when they are well maintained, they are golden resources. Tastypie did a good job, it put FAQs into "cookbook".

How to get support

Mailing list? IRC channel? Documents to record how to get help and communicate with the project community. Django is doing a good job of it.

Information to the contributor

In the project, people usually have the standard of how to do things. You should record it in the document so that others can write code that meets the criteria of the project. Open Comparison is doing well in this area.

Installation Instructions

Once people decide to use your code, they need to know how to get it and run it. I hope your installation instructions have only a few lines for basic use. If necessary, give a link to the page that provides more information and instructions. I think we did well in the Read the Docs.

your project license.

Bsd? MIT? Gpl? These certificates may be of little concern to you, but people who use your code will be very concerned about that. Consider what certificate you want to use to publish your project, and be sure to choose a standard license on the Internet.

What to do next

After you follow the above guidelines, we believe that your project will be successful. For further reference, see how this article maintains an open source project.

Template

Give you a README template. If you use markdown syntax, name it readme.md. If you use Restructuredtext syntax, name it readme.rst.

$project

========

$project would solve your problem of where to start with documentation,

By providing a basic explanation the IT easily.

Look easy it's 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 have 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.