Download to read offline
Uploaded byStreamNative
Code the docs-yu liu
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.
More Related Content
Code the docs-yu liu
- 1. Docs Like Code YuLiu Technical Writer Apache Pulsar & Apache Trafodion Committer
- 2. TOC • Challenges ofOpen Source Project • What is Docs Like Code? • Case Study (Apache Pulsar) • Benefits of Docs Like Code • Thoughts
- 3. Common Release Processof Docs
- 4. Issues • Docs arealways 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.
- 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 OpenSource 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 DocsLike Code?02
- 13. Definition • Docs arestored in a version control system (Git) - Sync doc w/ code - Resolve multiple version conflict • Unified collaboration environment (GitHub, GitLab) - Comprehensive ecosystem
- 14. Definition • Plain textfiles (AsciiDoc, Markdown) • Writing tools (VS Code, Eclipse, Sublime) - Writer: easy to learn and use - Dev: familiar - Integrate with other tools
- 15. Definition • Contents arecontinuously 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 BuiltUsing 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 onApache Pulsar03
- 19. Time-Based Release Planof 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 readyw/ codes in each release
- 21.
- 29. Benefits of DocsLike Code04
- 30. • Have morefocus 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 morefocus 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 teamsperform 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 • Docusaurusmakes 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 morefocus 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, devsperceive 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 LikeCode 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 andDoc 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 arecreated equal All professions deserve equal respect
- 41. • Have morefocus 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 areone 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 coreuser of Pulsar as well as a major contributor for Pulsar docs GitHub
- 45. Users Slack • Threaded conversations helpus 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 withusers directly and frequently • Identify users’ pain points • Foster empathy for users • Stand in users' shoes • Build quality technical info
- 47. • Have morefocus 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 justa 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 morefocus 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 realizesignificant 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 inDocs The niche or long tail docs are constructed from obscure knowledge gathering and hard-to-find information.
- 52. Issue • A singledev/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 projectmeans 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 inOpenStack Doc Contributions
- 55. Solution • Find specialiststo 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 morefocus 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 docbugs 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.
- 59. Pulsar live streaming(TGIP)
- 60. Docs Like Code •Highly automated • Efficient workflow • Friendly cooperation • Cost-effective tool
- 61. • The onlything 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.