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:
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:
Each document type serves a different purpose and has differing requirements — The Good Docs Project
Updated docs site
Please read our branding new docs site at http://wechaty.js.org/docs/ which following the concepts of documentation system!
基于标签的多功能服务系统&检测你身边的VIP用户