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 • • GitHub docs • RethinkDB • Cloud Canon • Jekyllrb • SendGrid • Beegit • Basket • Wistia help center • Liquid • Atlassian Design •

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