Developer guide-how to compile technical documents

Developer guide-how to compile technical documents

 

Why write a document?

You will use your code in 6 months

I found that it would be attractive to explain this question from the perspective of self-interest at the beginning. The best reason for writing a document is that you will use your code in 6 months. The code you wrote six months ago is usually no different from the code written by others. You will read your code with a familiar feeling. Then, a bad omen is quietly approaching. You find that the code writers have no experience or wisdom.

After reading the easy-to-understand or clever code a few months ago, you will start to sympathize with your users. As long as I write down why I want to do so, life will become so simple. The document allows you to record why the code is written in this way. Similarly, the code comments explain why, not how to do it. The same is true for the document.

You want others to use your code

You have written a piece of code and published it. You do this because you think others may find it useful. However, people need to know why your code may be useful to them before deciding to use it. The document tells people that this project is useful to them.

If people do not know the meaning of your project, they will not 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 few people will delve into your code and use it. Almost no one will use your code unless it has good documentation. If you really love your project, write a document for it and let others use it.

You need help from others

Open-source projects are magical, right? You published the code, and then the code gnomes appeared to make your code better.

When you publish code, you will have a wonderful feeling. It appears in various ways, but it will always make you excited. Is someone using my code? This is a mixture of fear and excitement.

I created value!

What if an error occurs ?!

I am an open-source project developer!

God, someone else is using my code...

This fear can be mitigated by written documents. A lot of fear comes from creating something for the world. My favorite citation for this question is as follows:

Fear is that you are doing important things.

If you are doing something that will not let you fear, it will be of no benefit to you or the world.

Congratulations! You are scared! It means you are doing important things.

Actually, this is not exactly the case.

Open-source projects are indeed surprising, but they must also comply with real-world rules. You must pay for what you get.

You can make a contribution only after you have paid a lot of work for the project.

Contribution can be made only when your project has users.

Contribution can be made only after your project has documents.

This document also provides a platform for your project's first contribution. Many people have never contributed to open-source projects, making code modifications much more terrible than modifying documents. If you do not have any documents, you will lose the contributors to such documents.

Documentation makes your code better

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

Writing documents can improve code design. 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 others contribute code according to your original intention.

You want to be a better writer.

Writing documents is different from writing methods that most people have experienced. Technical Writing is an innate art. Writing documents will be the starting point for you to become a better technology writer. As a programmer, this is a useful skill.

Writing will become easier as time passes. If you haven't written anything for months, it will become more difficult to start a new pen. Writing documents while working on projects will keep you at a reasonable pace of writing.

What tools are used for writing?

A simple start is the best way to achieve practical results. I will provide you with a smooth path. After you have basic ideas, you can expand the scope. These tools are powerful and easy to use. This removes the barriers to writing.

The examples in this article are valid in Markdown and reStructuredText. ReStructuredText is a bit difficult to use, but more powerful. I recommend that you check both of them and decide which one you want to use.

Plain text version control

As a programmer, we live in a world of plain text. Our document tools should not be exceptional. We want to convert plain text into beautiful HTML tools. We also have some of the best tools to track file changes. Why do we give up using these tools when writing documents? This set of workflows is powerful and familiar to developers.

Basic example

Resources

---------

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

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

The text above will be rendered as a title, with a list below. URLs will be automatically hyperlinks. This is easy to write. It makes sense not only for plain text, but also for HTML rendering.

README

The first document you should write is README. If you provide an appropriate extension, the Code hosting service will automatically render your README into HTML. It is also the first interaction between most users and your project. Therefore, a reliable README is very useful for your project.

Some people even start working on projects from README.

Document Writing

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

First, you need to ask yourself: who wrote the document. In the beginning, you only need to attract two types of readers:

User

Developer

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

What problems have your project solved?

Many people will use your documents to find out what your project is. Someone will mention it, and someone will randomly use Google to search for a phrase. You should explain what your project has done and its meaning. Fabric is doing well in this aspect.

A small example of code

Provide a vivid example to tell users what your project is usually used. Requests is a good example.

A link for code and problem tracking

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

FAQs)

Many people have the same problem. If the problem persists, modify your documents or code as appropriate to solve the problem. However, there are always some frequently asked questions about projects and things that cannot be changed. Keep these records in the document and keep them up-to-date. FAQs are usually outdated, but they are gold resources when they are well maintained. Tastypie is doing well. It organizes FAQs into Cookbook ".

How to obtain support

Email list? IRC channel? Documents should record how to get help and communicate with the project community. Django is doing well in this regard.

Contributor Information

In projects, people usually have standards for how to do things. You should record it in the document so that others can comply with the project standards when writing code. Open Comparison is doing well in this aspect.

Installation instructions

Once people decide to use your code, they need to know how to get it and run it. Hopefully, there are only a few lines of installation instructions for basic use. If necessary, provide a page Link to provide more information and instructions. I think we are doing well in Read the Docs.

Your Project License

BSD? MIT? GPL? These certificates may be useless to you, but those who use your code will be very concerned about this. Consider what certificate you want to use to publish your project. Be sure to select a standard license on the Internet.

What to do next

After you follow the above guidelines, we believe that your project will succeed. For more information, see How to maintain an open-source project.

Template

Here is a README template. If you use the markdown syntax, name it README. md. If you use the reStructuredText syntax, name it README. rst.

$ 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.