• World view
    • Why write technical documentation
    • Refute claims that you don’t need documentation
    • Seconded: Why read the document
    • What is a good technical document
    • Document & Write the definition of document
  • methodology
    • The tone
    • structure
      • Introduction
      • Content
      • Terms
      • Setup
      • Body
      • Reference
      • FAQ
      • Appendix
      • ChangeLog
      • ReleaseNote
    • process
    • tool
      • Writing tools
      • Maintenance tools
  • conclusion

The scope of documentation is extensive, and this article specifically refers to documents written by developers that cover the basic product background and major technical designs.

World view

Why write technical documentation

Personally, I find it easy to answer this question. Writing technical documents can help the team to complete the current information sharing and long-term knowledge transmission. For individuals, on the one hand, it saves time, because repeated questions are avoided and past knowledge is easily retrieved. On the other hand, it can build reputation. For example, once a colleague suddenly sent me a message saying that my documents were very good, which is very helpful to those who are new to this business.

Thank you from colleague XXX.

Refute claims that you don’t need documentation

There are many programmers who hold the view that “don’t read (write) documentation, it’s all in the code”, and others who believe that documentation is easily outdated and hard to keep up with the pace of the code, so there is no need to write documentation. All of this leads to a situation where you take over a business and joke that people don’t write documentation, and then you take over a business thinking that this stuff needs no explanation, no documentation at all. First of all, I personally don’t think it’s necessary to document the details of the code, but it’s absolutely necessary to document the overall design and business changes. Some people feel that documents are outdated because they didn’t introduce the concept of ChangeLog. Outdated documents are part of the history of the business, and I often need this historical information to understand when I take over a business.

Seconded: Why read the document

An interesting thing happened last week. A product told me, “Why should I read the documentation when I can explain it in two sentences?” Indeed, the brain is a powerful search engine. But in the long run, there are the following problems:

  1. Wasted development time

  2. Developers can’t answer at any time, wasting their time

  3. Information cannot be solidified, passed down, and is too trivial to waste team time

In general, a good technical document costs no more to understand than developing a dictation, or even less, because for much information, images can be expressed better than words.

What is a good technical document

I think the core of good technical documentation is agile. On the one hand, good technical documentation is highly maintainable and frequently maintained, with new features that allow the author to quickly update the document and the reader to get updates. Good technical documentation, on the other hand, is easy to understand and, in more detail, accurate in presentation, clear in structure, beautiful in layout, and consistent in style.

Document & Write the definition of document

Finally, I want to talk about what documentation is all about. Baidu Baike said:

A software document or source code document is a textual entity associated with a software system and its software engineering process.

So writing documentation is the process of producing this entity. But this is too abstract, and based on my experience over the last year, I prefer to define it as a process of structuring specific information.

So that’s the way of writing technical documentation, which is our basic worldview of the matter, and then the technique, which is the implementation methodology based on that.

methodology

The tone

There are three things we need to know before we start writing a document:

  1. Knowing enough: We need to document a module only if we know enough about the module to make our documentation valuable, otherwise it’s just garbage.

  2. Empathy: Even with the handover document, we often need to ask people transition, this kind of situation, in its essence, because many times we are stood in their point of view, according to own understanding to write documents, but the reader’s background information and we are not the same, we can think of of course they know nothing, So writing documents must have enough awareness of empathy. Documents are for others to read, not for yourself.

  3. MECE principle: In simple terms, it is mutually independent and completely exhaustive, and this idea guides our organization of document structure. A reference is given below.

structure

This chapter discusses each unit that a technical document should have, which can be used as a framework or Checklist for writing technical documents in the future.

Introduction

A brief Introduction of the project background information, such as the following Introduction I wrote for a project:

Content

Directory, directory is a direct reflection of the structure, must have, general document writing tools can automatically generate:

Terms

Terminology explanation, many businesses will derive some specific words, such as “white stripe card”, “big picture card”, etc., are specific context, need to be explained separately.

Setup

How to run this project, generally open source projects will have, if the SDK documentation is often also access documentation, is this module.

Body

This section is the main part of the document. The specific structure depends on the content and has the following general rules

  • A picture is worth a thousand words, such as the Android architecture diagram, the Actvity lifecycle diagram, better than any language.

  • Demo is worth a thousand words.

For detailed format specifications, you are recommended to read Ruanyf/Document-style-Guide: Writing Specifications for Chinese technical documents.

Reference

  • Related requirements: For example, all related requirements of a business are placed here, which is convenient for others to further understand the background, and also convenient for their own search.

  • Resources.

This section can also be included in the appendix, as shown below.

FAQ

Other people often ask questions, encountered on the record in this module, constantly supplement, gradually improve.

Appendix

Some of the more lengthy information can be put in the appendix, such as the journal, avoid putting in the body of the typesetting and reading.

ChangeLog

Changelog, a common open source project that records important changes for each release.

ReleaseNote

Release logs. Open source projects usually have a separate Release page.

process

Generally speaking, the document writing process is as follows: collecting information, organizing framework, practical conclusions, writing documents. If enough work is done, the time spent writing is minimal. In addition, after the completion of the document, also pay attention to reader feedback, in order to constantly improve their own document. Writing a good technical document is not accomplished overnight, it needs to be polished constantly, and it is necessary to pay attention to regular and deliberate practice.

tool

Writing tools

Generally speaking, whenever someone sends me a Word document, I put it in the lowest tier. I just want to ask two questions about this document:

  • How are updates to the document distributed to everyone who needs it?

  • Word format is not compatible with the key chart typesetting chaos how to do?

In general, document writing tools have the following options:

  • Word

  • Pdf

  • Markdown

  • Asciidoc

  • Latex

I strongly reject Word/Pdf, because many documents need to be updated, and these two formats cannot be updated dynamically. Markdown is popular with the open source community because it strikes a balance between expressiveness and simplicity, but it has a fatal problem with slightly more complex typography. Asciidoc is my main document tool, but many people don’t know that Github supports this document format, as this article does. Asciidoc’s syntax is more complex than Markdown’s, but I think the sacrifice of learning it is well worth it. Finally, Latex, a variant of Tex, is the most expressive and can cope with all kinds of complex typesetting. It is generally popular in academic circles (especially for the expression of complex mathematical formulas), but I think it is a bit overdone in everyday document writing. In summary, I recommend Asciidoc.

Maintenance tools

For documentation management, I recommend using Git to manage documentation as if it were code. In addition, I recommend using a static website to store your documents, so that when other colleagues visit, they will always see the latest documents. In addition, the company is currently promoting iWiki. I think the biggest advantage of iWiki is the permission control, which is necessary for some sensitive documents. However, as a programmer, I prefer Git to iWiki’s change log, and iWiki is a Web page, so the editing experience is certainly not as good as a locally configured editor. Of course, there is no absolute pros and cons of art, but also to see whether they are appropriate.

conclusion

Above, some thoughts on writing technical documents recently. Welcome to exchange comments.