Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Code the docs-yu liu

51 views

Published on

2019 china technical communication forum

Published in: Data & Analytics
  • Be the first to comment

  • Be the first to like this

Code the docs-yu liu

  1. 1. Docs Like Code Yu Liu Technical Writer Apache Pulsar & Apache Trafodion Committer
  2. 2. TOC • Challenges of Open Source Project • What is Docs Like Code? • Case Study (Apache Pulsar) • Benefits of Docs Like Code • Thoughts
  3. 3. Common Release Process of Docs
  4. 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. 5. Why do developers dislike documenting? Issue
  6. 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. 7. Challenges of Open Source Project01
  8. 8. Standards of Google • Season of Docs • Foster open source collaboration 
 with technical writers
  9. 9. Challenge • Development ways - Agile is popular - Frequent code/doc changes - Sync docs w/ code - Multiple versions
  10. 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. 11. Challenge • Communication (writer & dev) - Increased communication - Ways of thinking and working - Dev dislikes documenting - Dev thinks code is much more important
  12. 12. What is Docs Like Code?02
  13. 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. 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. 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. 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. 17. Case Study on Apache Pulsar03
  18. 18. 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
  19. 19. Docs are ready w/ codes in each release
  20. 20. Pulsar Doc Workflow
  21. 21. Benefits of Docs Like Code04
  22. 22. • 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
  23. 23. • 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
  24. 24. 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.
  25. 25. Pulsar Rest API - Swagger
  26. 26. 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.
  27. 27. • 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
  28. 28. 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.
  29. 29. 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.
  30. 30. 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
  31. 31. All men are created equal All professions deserve equal respect
  32. 32. • 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
  33. 33. 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.
  34. 34. Users is the core user of Pulsar as well as a major contributor for Pulsar docs GitHub 

  35. 35. 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.
  36. 36. Users • Communicate with users directly and frequently • Identify users’ pain points • Foster empathy for users • Stand in users' shoes • Build quality technical info
  37. 37. • 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
  38. 38. 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
  39. 39. • 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
  40. 40. 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.
  41. 41. Long-Tail Effect in Docs The niche or long tail docs are constructed from obscure knowledge gathering and hard-to-find information.
  42. 42. 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
  43. 43. 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
  44. 44. Long-Tail Effect in OpenStack Doc Contributions
  45. 45. 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.
  46. 46. • 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
  47. 47. • 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
  48. 48. Thoughts05
  49. 49. Pulsar live streaming (TGIP)
  50. 50. Docs Like Code • Highly automated • Efficient workflow • Friendly cooperation • Cost-effective tool
  51. 51. • 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.
  52. 52. Thank You

×