- 微博 QQ QQ空间 贴吧
Code the Docs by Yu Liu
2019 China Technical Communication Forum
1 .Docs Like Code Yu Liu Technical Writer Apache Pulsar & Apache Trafodion Committer
2 . • Challenges of Open Source Project • What is Docs Like Code? TOC • Case Study (Apache Pulsar) • Benefits of Docs Like Code • Thoughts
3 .Common Release Process of Docs
4 . Issues • Docs are always ignored • Docs are not synced with codes • Docs are inaccurate because many layers between developers, writers, and reviewers • Docs are incomplete due to long release cycle • Writers can not get technical inputs since developers dislike writing docs
5 .Issue Why do developers dislike documenting?
6 . Project Management Real Issue - What developers dislike is the workflow. Context-switch makes them reluctant to write and get docs done at the last minute. - Do we have a solution that integrate the doc process into a workflow which developers enjoy and solve the problems mentioned previously?
7 .01 Challenges of Open Source Project
8 . Standards of Google • Season of Docs • Foster open source collaboration with technical writers
9 . Challenge • Development ways - Agile is popular - Frequent code/doc changes - Sync docs w/ code - Multiple versions
10 . Challenge • Technology changes - Open source project provide service via API - Exponential growth of Rest API and SaaS - API docs are in urgent demand - Accuracy matter in API doc - Repetitive work
11 . Challenge • Communication (writer & dev) - Increased communication - Ways of thinking and working - Dev dislikes documenting - Dev thinks code is much more important
12 .02 What is Docs Like Code?
13 . Definition • Docs are stored in a version control system (Git) - Sync doc w/ code - Resolve multiple version conflict • Unified collaboration environment (GitHub, GitLab) - Comprehensive ecosystem
14 . Definition • Plain text files (AsciiDoc, Markdown) • Writing tools (VS Code, Eclipse, Sublime) - Writer: easy to learn and use - Dev: familiar - Integrate with other tools
15 . Definition • Contents are continuously tested, merged with each patch, built, deployed, and published automatically CI: Static site generator (Jekyll, Sphinx, Hugo) CD: Static site deployment tool (Jenkins, Netlify, CircleCI) - Reduce much repetitive and tedious work
16 .Doc Sites Built Using Docs Like Code Users of Doc Like Code • Stack Overflow Blog • Bootstrap • HealthCare.gov • GitHub docs • RethinkDB • Cloud Canon • Jekyllrb • SendGrid • Beegit • Basket • Wistia help center • Liquid • Atlassian Design • devo.ps
17 .03 Case Study on Apache Pulsar
19 .Time-Based Release Plan of Pulsar Strictly ensure Docs should be that Docs can be published a release dd blockers along with happens on for release a new release a given date
20 .Docs are ready w/ codes in each release
21 .Pulsar Doc Workflow
29 .04 Benefits of Docs Like Code