2019 china technical communication forum

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

5. Why do
developers
dislike
documenting?
Issue

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

21. Pulsar Doc Workflow

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