Code the Docs by Yu Liu

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 

18 .

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 

22 .

23 .

24 .

25 .

26 .

27 .

28 .

29 .04 Benefits of Docs Like Code