Applying the documentation system to Wechaty docs

最新推荐文章于 2023-04-10 22:59:18 发布

原创最新推荐文章于 2023-04-10 22:59:18 发布 · 122 阅读

CC 4.0 BY-SA版权

本文介绍了Wechaty组织如何应用Google Season of Docs，借鉴Daniele Procida的'The Grand Unified Theory of Documentation'，将文档分为教程、指南、技术参考和解释四种类型，重构了网站并提出GSoD提案。Good Docs Project也提供了宝贵的资源，帮助改进开源软件文档。

This year, Wechaty organization is applying the Google Season of Docs program because we want to improve our documentation for the community.

When I’m reading Google Season of Docs - Project Ideas, I found this great talk: What nobody tells you about documentation, Daniele Procida, 2017, PyCon AU, which techs me The Grand Unified Theory of Documentation:

There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.

They are: tutorials, how-to guides, technical references, and explanations. They represent four different purposes or functions and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.

What nobody tells you about documentation

In the Daniele’s 30 minutes talk video, I decided to follow his principle to refactor our Wechaty Documentation website.

What nobody tells you about documentation, Daniele Procida, 2017, PyCon AU

In the above video, Daniele “using real-life examples I’ll draw out the key functions of documentation, and how they map onto different ways of writing it. Putting this into practice is simple when armed with some basic guidelines. The benefits are huge, and available with a minimum of effort.” (link)

The most important concept is the following diagram:

The Documentation System

Credit: Documentation System

By following the above concepts, I re-structured our docs site by a better understanding of what Wechaty documentation should be like, and also great help me to write a better GSoD proposal for submitting to Google.

The Good Docs Project

The Good Docs Project is also a great project with huge helps.

The goal of the Good Docs Project is to improve open source software documentation by providing high quality templates and writing instructions to the open source community and beyond.

The following diagram illustrated the lifecycle of the documentation:

The Good Docs Project