Docs Like Code in Enterprise

Docs Like Code in Enterprise

Nick Volynkin

Technical writer, Plesk

Docs Like Code

  • What it is
  • Benefits
  • How to adopt it
_images/plesk_logo.png

Plesk

Hosting control panel

  • 377 000 servers

  • 11 000 000 websites

  • 6% websites on the Internet

    (Research by Netcraft, March 2017)

docs.plesk.com

  • 20 guides
  • 10 languages
  • Current and earlier product versions
  • 4072 pages only in English

Author IT (since 2005)

  • WYSIWYG editor (Windows only)
  • Single source
  • Database storage
  • Localization
  • Publishes to HTML

Problems

  • No version control or rollbacks
  • Review by email
  • No support for product versions
  • Uncontrolled manual publishing

Requirements

  • Version control and rollbacks
  • Collaboration and team workflow
  • Product versions
  • Automated and controlled publishing
  • Migrating content

Nice to have

  • Keep site structure for SEO
  • Cross-platform
  • Open source
  • Active community

Options

  • Other authoring system
  • Wiki-based
  • Confluence
  • DITA
  • Docs like code

Docs like code

  • Writing docs source in a lightweight markup language
  • Treating it like program code

Lightweight Markup Languages

  • Readable by a human
  • Structured for machine

reStructuredText + Sphinx

Python, Mozilla, Ansible, OpenStack,

Plesk

_images/lists-code.png _images/lists-html.png
_images/links-code.png _images/links-html.png
_images/tables-code.png _images/tables-html.png
_images/admonition-code.png _images/admonition-html.png
_images/features-code.png _images/features-html.png
_images/structure-code.png
_images/structure-html.png

Templates

Data → Formatted output

<!DOCTYPE html>
<head>
  {% block htmltitle %}
  <title>{{ title }}</title>
  {% endblock %}
  <!-- ... -->
</head>
<body>
  {% block header %}
  {% include header.html %}
  {% endblock %}
  <!-- ... -->
  {% block footer %}
    {% include footer.html %}
  {% endblock %}
</body>

Themes

  • Templates
  • CSS
  • Dynamic content
  • Anything else

Generating output with:

  • command-line program
  • code library
  • GUI

~ 5-10 seconds

Output formats:

  • HTML
  • PDF
  • DOCX
  • EPUB
  • Unix manpages

Req. 1: Version control, branches and rollbacks

Git!

Diffability

git diff

Blameability

git blame

Share repositories with products?

No

Single or multiple repositories?

Guide ←→ Git repo

Req. 2: Collaboration and team workflow

Stable Git branches

Reviewed, approved and published docs.

Feature branches

Work in progress.

One task ←→ one feature branch

Pull (merge) request

feature → master

Team workflow

Req. 3: Product versions

Multiple stable Git branches

Req. 4.1: Automated publishing

Continuous integration server

Local build = server build

  • Feature branch → test-docs.plesk.com
  • Stable branch → docs.plesk.com

Req. 4.2: Controlled publishing

pull requests!

Doc book ≈ microservice

Req. 5: Migrate content

Problem 0: Tools?

Pandoc for markup

from 21 to 40 markup formats

  • HTML
  • MS Word
  • Latex
  • DocBook
  • Markdown
  • reStructuredText

Python for structure

~100 lines of code

Problem 1: Sources

No DB source for earlier versions

Using HTML output as source

Problem 2: Continuous changes

Migrating with program code

No manual actions!

Problem 3: Converting styles

Source Target
20 inline styles inline markup and
70 paragraph styles lots of directives

Solution: Style Map

Source Target
Header # Header #
Internal link docs.plesk.com/... Reference link markup
“Special bold” GUI item, term, plain text…
Code PHP, Bash, Python…

What's next?

  • Testing documentation
  • Advanced Analytics
  • A/B tests
  • Interactive API docs

How to Start

1. Make a Prototype

Fork a repository on GitHub/GitLab and make changes

2. Collaborate and publish with VCS

Same release cycle => same repository

Use pull requests for review and acceptance

3. Automate From the Start

Local build = Server build

4. Migrate Content

Define style and structure mapping

Use pandoc and other conversion tools

5. Drink Your Own Champagne

Document your new tools with themselves

6. Ask Questions

ru.stackoverflow.com

stackoverflow.com

7. Join the Community

Write The Docs

t.me/technicalwriters

Get in Touch