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
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