Code the docs-yu liu
•
2 likes•895 views
The document discusses the concept of "Docs Like Code", which treats documentation like code by storing docs in version control systems, using plain text formats, and integrating doc writing and publishing into the same workflow as software development. It provides the case study of Apache Pulsar, which uses GitHub and other tools to collaborate effectively on docs between developers, writers and users. Benefits include better doc quality and syncing with code through continuous integration/deployment of docs.
Code the docs-yu liu
- 1. Docs Like Code Yu Liu Technical Writer Apache Pulsar & Apache Trafodion Committer
- 2. TOC • Challenges of Open Source Project • What is Docs Like Code? • 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
- 6. Real Issue Project Management - 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. Challenges of Open Source Project01
- 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. What is Docs Like Code?02
- 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. Case Study on Apache Pulsar03
- 19. Time-Based Release Plan of Pulsar Strictly ensure that a release happens on a given date d d Docs should be published along with a new release Docs can be blockers for release
- 20. Docs are ready w/ codes in each release
- 29. Benefits of Docs Like Code04
- 30. • Have more focus on contents • Promote collaborations Writer + Dev Writer + User All members • Get long-tail contributions • Track doc bugs like code bugs • Obtain better reviews • Make beautiful docs • Use cost-effective tools
- 31. • Have more focus on contents • Promote collaborations Writer + Dev Writer + User All members • Get long-tail contributions • Track doc bugs like code bugs • Obtain better reviews • Make beautiful docs • Use cost-effective tools
- 32. Reason • Development teams perform continuous integration and deployment automatically, docs work the same way. • Docs can have tests to ensure quality, such as broken link tests, white-space tests or spell checking. • Docs can be published automatically after trusted reviewers merge changes into the repository. • Docs can use continuous builds to ensure that they build and publish correctly.
- 33. Pulsar Rest API - Swagger
- 34. Pulsar Localization • Docusaurus makes it easy to use translation functionality using Crowdin. • Pulsar Website Build pulls down and uploads translation for all Pulsar docs automatically. • Once it pulls down translation from Crowdin, it will build the translation into the website automatically.
- 35. • Have more focus on contents • Promote collaborations Writer + Dev Writer + User All members • Get long-tail contributions • Track doc bugs like code bugs • Obtain better reviews • Make beautiful docs • Use cost-effective tools
- 37. Issue • Sometimes, devs perceive that writers are distant from the product, and they consequently treat writers like second-class citizens. Thought • The second product of a product is Docs.
- 38. Solution • Docs Like Code make writers use the same workflow and tool as devs, which reduces communication barriers and makes agile docs. • Agile doc development drive writers to sync docs w/ codes and learn more. • Writers can communicate w/ devs equally and even have more broad views than devs on some aspects of products.
- 39. GitHub • Code and Doc Workflow is same Counts codes and docs contributions equally (commit) • Dev and Writer Same voting privilege and weight Same opportunity to awarded as committer or PMC
- 40. All men are created equal All professions deserve equal respect
- 41. • Have more focus on contents • Promote collaborations Writer + Dev Writer + User All members • Get long-tail contributions • Track doc bugs like code bugs • Obtain better reviews • Make beautiful docs • Use cost-effective tools
- 43. Users • Users are one of the most important authors of Pulsar docs and they drive community growth. • GitHub and its comprehensive ecosystem provides highly-effective communication platform.
- 44. Users is the core user of Pulsar as well as a major contributor for Pulsar docs GitHub
- 45. Users Slack • Threaded conversations help us for deep discussions around a specific topic without clogging up the channel with details. • Deeply integrate with GitHub, Jira, Twitter, Zoom, Google Drive and Calendar, and other tools.
- 46. Users • Communicate with users directly and frequently • Identify users’ pain points • Foster empathy for users • Stand in users' shoes • Build quality technical info
- 47. • Have more focus on contents • Promote collaborations Writer + Dev Writer + User All members • Get long-tail contributions • Track doc bugs like code bugs • Obtain better reviews • Make beautiful docs • Use cost-effective tools
- 48. Users GitHub • Not just a code hosting platform, it is a social network • Contribution graphs: encourage everyone to build a better online resume show everyone's specialty and provide opportunity to cooperate with the best talent
- 49. • Have more focus on contents • Promote collaborations Writer + Dev Writer + User All members • Get long-tail contributions • Track doc bugs like code bugs • Obtain better reviews • Make beautiful docs • Use cost-effective tools
- 50. Long-Tail Effect Companies realize significant profits by selling low volumes of hard-to-find items to many customers, instead of only selling large volumes of a reduced number of popular items.
- 51. Long-Tail Effect in Docs The niche or long tail docs are constructed from obscure knowledge gathering and hard-to-find information.
- 52. Issue • A single dev/writer/team can’t know an entire software product. • For a complex software products, only a few people understand deeply. Thought • Fight together
- 53. Open source project means everyone can: • contribute • use freely Docs Like Code and its comprehensive ecosystem: • make effective collaboration across distributed teams • explore advantages of each role to the greatest extent
- 54. Long-Tail Effect in OpenStack Doc Contributions
- 55. Solution • Find specialists to collaborate with. If they are motivated to write content for that small, focused area of the product, those technical details can make a huge difference in the success of an information product, especially one targeted to developers. • Split deliverables into parts that encourage small but mighty contributions.
- 56. • Have more focus on contents • Promote collaborations Writer + Dev Writer + User All members • Get long-tail contributions • Track doc bugs like code bugs • Obtain better reviews • Make beautiful docs • Use cost-effective tools
- 57. • Track doc bugs like code bug When you give your readers a way to track doc issues, they can tell you where they found confusing or incorrect content and even how to fix it. • Obtain better reviews Code system workflows encourage small changes that are easy to compare, you can get more reviews. When you treat docs like code, reviewers can see final changes in context before approving them. • Make beautiful docs • Use cost-effective tools
- 58. Thoughts05
- 59. Pulsar live streaming (TGIP)
- 60. Docs Like Code • Highly automated • Efficient workflow • Friendly cooperation • Cost-effective tool
- 61. • The only thing that is constant is change. • Docs Like Code is an innovation and integration across boundaries in today's fast-paced world. • Technical communicators should be proud of who they are for having open-minded attitude and embracing challenges.
- 62. Thank You