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
Plesk
Hosting control panel
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
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!
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
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!
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
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