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.
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 conﬁgured with plugins
for reporting coding style violations, you can conﬁgure 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.
Why should I use it
➔ Consistent, tested APIs and
documentation can help your product
and your development cycle.
➔ Consistency is a important trust
➔ Writing your documentation
according to a deﬁned standard
reﬂecting your product and company
is good for SEO.
Word of advice
➔ 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, workﬂows and a solid base and
understanding of security is
Word of advice
➔ Make sure that all your tests are
working, that you can trust the
results, and that your infrastructure is
well conﬁgured and secure.
➔ Developers, DevOps, and your Site
Reliability (SRE) teams can assist you
to make sure everything is set up
➔ These are critical to quality, you do
want to make sure that you conﬁgure
your git repositories properly, set
Content Strategy and Design
➔ 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.
Docs As Code breaks down into ﬁve points:
➔ Content strategy
➔ Editorial style guidelines
➔ Content analytics
➔ Automated testing
➔ Deploying (publishing)
Docs As Code
Run Q&A Checks
API and Documentation Quality Assurance
Quality assurance (QA) is the process of verifying
whether a product meets the required speciﬁcations
and customer expectations
API and Documentation
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
➔ Consistent docs are a trust signal.
A deeper knowledge of engineering tools, workﬂows 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
Where to start
Deﬁne your goals
A good ﬁrst step is to determine what you want to achieve.
➔ Deﬁning a style guide
➔ User stories