Many of us have heard about Docs As Code. Applying the same tooling and delivery CI/CD (Continuous Integration and Continuous Delivery) pipelines as developers to improve the quality of (API) documentation sounds nifty. We’ll take a look at the philosophy, best practices and how to get started.

1. 1
Engineer stunning (API)
documentation
Docs As Code
Sven Strack • @der_sven_ • DocOps Engineer @ PRONOVIX

2. 2
WELCOME

3. ABOUT Docs As Code
Building, maintaining and continually improving (API)
documentation by doing Docs As Code the DocOps way.

4. OVERVIEW
4
Agenda
➔ Introduction to Docs As Code
➔ Advantages of QA testing of API and related
documentation
➔ Start local
➔ Use CI/CD, too

5. DEFINITION
5
Stunning
stun·ning | ˈstə-niŋ
: strikingly impressive especially in beauty or excellence
It’s about ALL aspects of (API) documentation
➔ Appealing appearance
➔ Content structure
➔ Clearity
➔ Grammar
➔ SEO
➔ Accessible

6. Docs As Code

7. DOCS
AS CODE
7
Introduction
Applying the Docs As Code method assumes that you use the
same tooling for writing documentation which you use for working
on your code.
In the same manner that code editors are configured with plugins
for reporting coding style violations, you can configure your code
editor with plugins that report inconsistencies with your company's
editorial and content style guides.
Depending on your documentation, these could be plugins for
checking the consistency of your markup language and your
editorial style-guide, like the use of US or UK English, the style of
headings, the length of documents and many more.

8. DOCS
AS CODE
Why should I use it
➔ Consistent, tested APIs and
documentation can help your product
and your development cycle.
➔ Consistency is a important trust
signal.
➔ Writing your documentation
according to a defined standard
reflecting your product and company
is good for SEO.

9. 9
ATTENTION

10. Word of advice
Avoid disaster!
➔ Working with Docs As Code can help
you improve the quality and speed up
the publication process, but it also
has a learning curve.
➔ A deeper knowledge of engineering
tools, workflows and a solid base and
understanding of security is
necessary.
DOCS
AS CODE

11. DOCS
AS CODE
Word of advice
➔ Make sure that all your tests are
working, that you can trust the
results, and that your infrastructure is
well configured and secure.
➔ Developers, DevOps, and your Site
Reliability (SRE) teams can assist you
to make sure everything is set up
properly.
➔ These are critical to quality, you do
want to make sure that you configure
your git repositories properly, set
permissions, etc.

12. DOCS
AS CODE
Content Strategy and Design
12
➔ Message architecture
➔ Editorial Style Guidelines
➔ Markup Style Guidelines
➔ Objectives and key results
➔ “ROT” analysis (Redundant, Outdated, Trivial)
“If you don’t know what you want or need to
communicate, how will you know if you succeed?”
This is where content strategy and design can help.

13. DOCS
AS CODE
Core Subjects
Docs As Code breaks down into five points:
➔ Content strategy
➔ Editorial style guidelines
➔ Content analytics
➔ Automated testing
➔ Deploying (publishing)

14. WORKFLOW
14
Docs As Code
Write
Text Editor
Style Guide
Commit
VCS
Version Control
System
CI/CD
Run Q&A Checks
Deploy
Trigger Deploy
Request Review
Pull
Request
Merge
New
Version
Online

15. 15
WORKFLOW

16. Quality Assurance

17. QUALITY
ASSURANCE
API and Documentation Quality Assurance
Quality assurance (QA) is the process of verifying
whether a product meets the required specifications
and customer expectations

18. API and Documentation
Quality Assurance
Why is QA important?
➔ Product documentation is an important marketing asset for
promoting both your product and your organization.
➔ Good documentation helps you to satisfy your customers.
➔ Happy clients, it also means less support work and thus, more
time for other projects. It will also save your company money.
➔ Good documentation gets people to jump into your project
quicker
➔ Consistent docs are a trust signal.
QUALITY
ASSURANCE

19. DO NOT
FORGET
Friendly reminder
A deeper knowledge of engineering tools, workflows and a solid base
and understanding of security is absolutely necessary to set up a Docs
As Code way of working.
➔ Protect your branches
➔ Validate all your checks according to best practices
➔ Keep checks “simple” and “easy” to adjust
➔ Start small
➔ Make your checks depending on each other
19

20. 20
Where to start
Define your goals
A good first step is to determine what you want to achieve.
➔ Defining a style guide
➔ User stories
➔ Analytics
QUALITY
ASSURANCE

21. Quality Assurance _> local

22. QA LOCAL
22
Quality Assurance starts locally
Remember

23. LOCAL
QUALITY
ASSURANCE
23

24. LOCAL
QUALITY
ASSURANCE
24
Almost stunning

25. Quality Assurance _> with CI/CD

26. QA with
CI/CD
Continuous Integration
GitLab – AWS Pipeline – GoCD – Semaphore – and many more

27. CONTINUOUS
INTEGRATION
27
Automated QA Checks
CircleCI

28. 28
CONTINUOUS
INTEGRATION
Automated QA Checks
GitLab

29. 29
CONTINUOUS
INTEGRATION
Automated QA Checks
Drone CI

30. 30
CONTINUOUS
INTEGRATION
Automated QA Checks
GitHub Action

31. 31
CONTINUOUS
INTEGRATION
Automated QA Checks
GitHub Action

32. RECAP
32
Key Takeaways
➔ Know what you want to check
➔ Start early
➔ Start small
➔ Start local
➔ Make sure checks a valid and working
➔ Work secure
➔ Take your time
➔ Reevaluate

33. QUESTIONS
33

34. 34
Your Host for Today
Sven Strack
DocOps Engineer @Pronovix
ABOUT ME

35. Sven Strack
DocOps Engineer
sven.strack@pronovix.com

36. Developer portal mailing list
bit.ly/devportals
36Pronovix confidential and proprietary