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?
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
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
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
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.
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
36.
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
42.
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
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
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.
