When you treat docs like code, you multiply everyone’s efforts and streamline processes through collaboration, automation, and plain old hard work. To create a cohesive API experience, developers, technical marketing engineers, technical writers, and product managers can work together on GitHub to produce web pages and API documentation, including interactive API docs and tutorials. The ways you can leverage developer processes and tools in a docs-as-code system vary widely. Let's walk through some examples including tools, version control, publishing workflows, approvals, source formats, checklists, automated testing, and final approval. Also, let's take some time to share some of the pitfalls and difficulties possible when you work on API and tools documentation for a large and varied product catalog with more than a thousand contributors.

1. Anne Gentle
Developer Experience Manager
September 8, 2022
Publishing Processes
for API Experiences
Docs as Code

2. © 2022 Cisco and/or its affiliates. All rights reserved. 2
Hi!
• I’m a Developer Experience Manager for
Cisco DevNet.
• We treat docs like code for over 1000
code repositories for multiple developer
products and platforms at Cisco.
• There’s a book and site, Docs Like Code,
to provide better onboarding for these
techniques.
• Find the story about Cisco DevNet on
docslikecode.com.

3. Define docs as code
GitHub or GitLab as a CMS
(Content Management System)
Version control for documentation source files (close to code)
Automatic builds for docs
Test the docs (close to code)
Review with technical collaborators
Merge the docs
Continuous integration, continuous deployment
Publish (possibly automatically after requirements are met)
Repeat

4. © 2022 Cisco and/or its affiliates. All rights reserved. 4
© 2022 Cisco and/or its affiliates. All rights reserved.
DevNet Program
Questions in Webex
• Question comes in on
12/02/2020 at 1:30 pm Central
• Team size, you ask?
• Two central dev doc coordinators
• Three contract technical writers
(one intern at that time)
• Many tools and platforms engineers
• 1,700+ PubHub contributors

5. © 2022 Cisco and/or its affiliates. All rights reserved. 5
What is the process and who are the
authors?
What API documentation and
developer tutorials do you create?
What are the tools?
What parts are difficult?
Agenda
1
2
3
4

6. © 2022 Cisco and/or its affiliates. All rights reserved. 6
What is the process
and who are the authors?

7. © 2022 Cisco and/or its affiliates. All rights reserved. 7
Typical questions:
• Who are your targeted developers and
top use cases?
• How can DevNet help meet your goals?
• Tell us about your content, is it currently
published anywhere, do you have login or
access requirements, what is created
already, what needs to be created?
• Is there any important messaging or an
event for DevNet to know about?
Onboarding form – filled out by Cisco Business Unit
representative

8. © 2022 Cisco and/or its affiliates. All rights reserved. 8
• Developers
• Engineers
• Technical Marketing Engineers
• Technical Writers
• Product Managers
Technical staff at Cisco

9. © 2022 Cisco and/or its affiliates. All rights reserved. 9
• Activity represents internal drafts and
preview on staging.
• For example, 13 changes on a
Tuesday last week.
• 70 changes in 2 weeks included a
US holiday week.
• Nothing gets published without a
person reviewing.
• With enough trusted tests, you can
have true CICD for documentation.
Repository = PubHub project
Activity = green graph lines

10. © 2022 Cisco and/or its affiliates. All rights reserved. 10
What API documentation and
developer tutorials do you
create?

11. Landing pages and dev centers:
XML, HTML
Technical documentation:
Markdown, JSON, HTML
Interactive API documentation:
OpenAPI specification
(YAML or JSON)
Interactive tutorials: Dockerfile, code
Pages on developer.cisco.com
Developer content

12. © 2022 Cisco and/or its affiliates. All rights reserved. 12
© 2022 Cisco and/or its affiliates. All rights reserved.
Technical
documentation
• Sidebar table of contents.
• Markdown source files for text.
• JSON source for organization.
• Multiple configuration options
for Next/Prev buttons, TOC
expansion, code examples.
• pubhub.cisco.com/docs

13. © 2022 Cisco and/or its affiliates. All rights reserved. 13
© 2022 Cisco and/or its affiliates. All rights reserved.
Interactive
REST API docs
• Industry-standard OpenAPI
source files
• Meraki source:
https://raw.githubusercontent.c
om/meraki/openapi/master/op
enapi/spec2.json

14. © 2022 Cisco and/or its affiliates. All rights reserved. 14
© 2022 Cisco and/or its affiliates. All rights reserved.
Try out the Meraki
REST API
• Created API Key and Organization
data for everyone to use: read-
only access.
• User can enter their own
credentials and make real calls.
• Python SDK examples for every
endpoint.
• Postman Collection provided
separately.

15. © 2022 Cisco and/or its affiliates. All rights reserved. 15
© 2022 Cisco and/or its affiliates. All rights reserved.
Interactive
Learning Center
• Student reads or does hands-on activities
• System tracks progress
• For interactive Labs, system launches
interactive terminal and file system in-
browser using containers on Kubernetes
cluster
• Labs that require Cisco gear use
Sandboxes or other infrastructure

16. © 2022 Cisco and/or its affiliates. All rights reserved. 16
© 2022 Cisco and/or its affiliates. All rights reserved.
Interactive tutorials
• Author starts with a Docker
container, installs what they
want to teach.
• Author writes Markdown with
Python or Bash commands
that the student runs in the
browser.

17. © 2022 Cisco and/or its affiliates. All rights reserved. 17
What are the tools?

18. © 2022 Cisco and/or its affiliates. All rights reserved. 18
Author
• Visual Studio Code
(Acrolinx plugin)
• editor.swagger.io
(OpenAPI)
• Vim or Emacs
Tools
Source Control
• Git
• Git Bash
• GitHub
• GitHub Desktop
Develop
• OpenAPI
• Docker
• Python
• JavaScript

19. © 2022 Cisco and/or its affiliates. All rights reserved. 19
Author and Source Control –
making changes
Create a
branch
Get ready to make your
changes
Commit the
changes
Save your work
Clone the repo
Make a local copy of the
code repository
Make your
changes
Create, edit, add, delete
Push your
branch
Preview the changes
PR

20. © 2022 Cisco and/or its affiliates. All rights reserved. 20
Reviewer and Source Control –
approving changes
Write
comments
Write inline comments to
the author
Approve the
changes
Save your work
Review the pull
request
Visual diff in GitHub UI
Author makes
your changes
Create, edit, add, delete,
and push back to GitHub
Preview and/or
publish
Use PubHub UI to approve
and push to
developer.cisco.com

21. © 2022 Cisco and/or its affiliates. All rights reserved. 21
© 2022 Cisco and/or its affiliates. All rights reserved. Cisco Confidential
Authoring tool
Any text-based editor or IDE
(Integrated Developer
Environment).

22. © 2022 Cisco and/or its affiliates. All rights reserved. 22
© 2022 Cisco and/or its affiliates. All rights reserved. Cisco Confidential
Visual Diff
Red is removed, green is
added.
Comments can be inline or
overall.

23. © 2022 Cisco and/or its affiliates. All rights reserved. 23
© 2022 Cisco and/or its affiliates. All rights reserved.
PubHub preview
• Published project has current
production state.
• List of collaborators all have
access to work on this project.
• Change detected shows the
preview, organization and layout
only.
• To preview on staging you
”Request to publish” – and repeat.

24. © 2022 Cisco and/or its affiliates. All rights reserved. 24
© 2022 Cisco and/or its affiliates. All rights reserved. Cisco Confidential
editor.swagger.io
• Online editor that validates.
• Files can be YAML or JSON.
• OAS training available for
technical writers, engineers,
product managers, and
developers to learn the
OpenAPI specification.

25. JSON vs. YAML: Side-by-side
YAML
JSON

26. © 2022 Cisco and/or its affiliates. All rights reserved. 26
© 2021 Cisco and/or its affiliates. All rights reserved. Cisco Confidential
Training:
OAS v3 Elements
OpenAPI 3.x
info
servers security
paths
tags externalDocs
components

27. 27
info

28. © 2022 Cisco and/or its affiliates. All rights reserved. 28
OAS Elements: Info Example info

29. © 2022 Cisco and/or its affiliates. All rights reserved. 29
Describes one or
more API endpoints
for cloud and on-
premises APIs
They may be a
complete URL or use
variable substitution
OAS Elements: Servers (aka Hosts) servers

30. © 2022 Cisco and/or its affiliates. All rights reserved. 30
Operation = Path + HTTP
Method
Query parameter
• GET /alarms?active=true
200: Response with payload
OAS Elements: Paths
paths
Learn more about status codes
https://developer.cisco.com/apistyleguide/#rest-style/returning-
http-status-codes

31. © 2022 Cisco and/or its affiliates. All rights reserved. 32
Define reusable structures for
request inputs and response
outputs.
Often referenced from
operations or from one schema
to another.
Helpful for keeping “Don’t
Repeat Yourself” DRY
principles.
OAS Elements: Schema Components
components

32. © 2022 Cisco and/or its affiliates. All rights reserved. 33
Four-day training is a deep
dive
Still need to version-control
improvements if the spec is
generated
Reuse is possible with OAS
OpenAPI
Docs improvements
OpenAPI 3.x
info
servers security
paths
tags externalDocs
components

33. © 2022 Cisco and/or its affiliates. All rights reserved. 34
What parts are difficult?

34. © 2022 Cisco and/or its affiliates. All rights reserved. 35
• Teams compare one product API
metrics to another, but they’re not
similar. At all.
• Engineers learn ”just enough”
OpenAPI Specification to generate it
automatically. Try to set it and forget
it.
• Automated testing is difficult! So far,
we have only figured out half of the
equation, the container half.
API Docs are Hard
Anyone who says otherwise, well…

35. © 2022 Cisco and/or its affiliates. All rights reserved. 36
Getting Actionable Feedback
• Was the information in the document accurate?
• Was the information in the document relevant?
• Was the information in the document easy to understand?
• Could you find the information you needed in the document?
Beyond Accuracy: What Documentation Quality Means to Readers
February 2019
Technical Communication (Washington) 66(1):7-29
Accurate, Relevant, Easy to Understand, Accessible

36. © 2022 Cisco and/or its affiliates. All rights reserved. 37
PowerBI Dashboard
Metrics
NPS = Net Promotor Score
Promoter = 9 or 10
Passive = 8, 7, 6, 5, 4
Detractor = 3, 2, 1
Star Rating = 1-5 stars

37. © 2022 Cisco and/or its affiliates. All rights reserved. 39
© 2022 Cisco and/or its affiliates. All rights reserved. Cisco Confidential
Summary
Process: Docs as Code,
onboarding for documentation,
infrastructure, developer
experience needs.
Authors: technical contributors on
Enterprise GitHub.
Output: developer.cisco.com
landing pages, technical
documentation, interactive API
docs and interactive learning.
Tools: Editors, IDEs, OpenAPI,
Docker, PubHub, PowerBI, Git, and
GitHub.

38. © 2022 Cisco and/or its affiliates. All rights reserved. 40
Links
• Documenting APIs: A guide for technical writers and engineers
• Docs Like Code: https://docslikecode.com
• GitHub Pages: https://pages.github.com
• Meraki API Docs: https://developer.cisco.com/meraki/api-v1/
• Meraki OpenAPI Spec: https://github.com/meraki/openapi
• Measuring documentation quality through user feedback:
https://idratherbewriting.com/learnapidoc/docapis_measuring_impact.html
Where to find out more
We are hiring!
https://cs.co/api-quality-job
Scan for job link!

39. © 2022 Cisco and/or its affiliates. All rights reserved. 41
Q&A

41. © 2022 Cisco and/or its affiliates. All rights reserved. 43
Reference information

42. © 2022 Cisco and/or its affiliates. All rights reserved. 44
Source
• GitHub can do version control, but
isn’t used on source files currently in
the “GitHub tagged release” way.
• Branches do let us have fine control
of each change but that is not the
same as version control.
• We could automate source release
production using the GitHub API.
Output
• PubHub has a way to indicate the
version group for a PubHub project
so that the output has a drop-down
version menu.
Version control

43. © 2022 Cisco and/or its affiliates. All rights reserved. 45
Git
• Version control technology
• Widely used across the industry
• Interaction with command line
interface (CLI) or graphical user
interface (GUI)
• Services include: GitLab, BitBucket,
and GitHub
GitHub
• Cloud-based git host
• Public: github.com
• Cisco enterprise: wwwin-
github.cisco.com
Git and GitHub as a CMS

44. © 2022 Cisco and/or its affiliates. All rights reserved. 46
GitHub terms
• Repository: A collection of content or code
• Branch: A set of changes within a repository
• Each branch has a unique name
• Branch can exist locally and on GitHub
• Commit: Saving changes at a point-in-time or a selected point of completion
• Push: Sending a Commit to the collaborative GitHub UI for review
• Merge: Adding the code from one branch to another
• Pull Request: A collection of changes from a commit ready for review
Useful vocabulary to have; quite specific to Git

45. © 2022 Cisco and/or its affiliates. All rights reserved. 47
Content Authors
Enterprise GitHub /
github.com
Content
Source
DevNet
DevNet Site
App
Course App
(Custom Render)
Publish
S3
(Public & Protected)
CloudFront Metadata
Service
HTML/Web, Markdown, Swagger..
Preview +
Publish Stage
Editor/Approver
Pubhub
Authoring Editing Review Approve Render
Versioning Search
PubHub
Architecture