Engineering Documentation

Engineering Documentation Lorna Mitchell, Aiven

Engineering is about solving problems and helping people @aiven_io ~ @lornajane

Documentation enables customer success @aiven_io ~ @lornajane

Colleague enablement Share the secrets with your team, on their level @aiven_io ~ @lornajane

Diátaxis https://diataxis.fr @aiven_io ~ @lornajane

Style guide •use a specific template •add hyperlinks •use active wording •formatting guidelines •positive and respectful language •titles, verbs and sentence case •screenshots and example values •what not to do @aiven_io ~ @lornajane

Content structure Consistent navigation patterns •products •tools Put developers in control by offering really good search •we use Aiven for OpenSearch •indexing multiple sources @aiven_io ~ @lornajane

Docs as Code Use the same tools and workflows as for code @aiven_io ~ @lornajane

Source control •easy to work on many parallel changes •identify of author and reviewer are known •full change history for all pages •collaboration tools for big or small changes @aiven_io ~ @lornajane

Text-based markup •static site generator •separate content and presentation •reuse content (single sourcing) •handle large changesets easily @aiven_io ~ @lornajane

Text-based diagrams Using https://mermaid-js.github.io @aiven_io ~ @lornajane

Tooling Editors with: •syntax highlighting •side-by-side preview •git support GitHub web interface for quick edits •preview feature for pull requests @aiven_io ~ @lornajane

Automating a docs platform @aiven_io ~ @lornajane

Continuous integration Pull request build does the work •verify the build •generate preview •check hyperlinks •prose linting with Vale @aiven_io ~ @lornajane

Vale Prose linter https://vale.sh/ •checks for valid words and can be taught technical terms •checks for correct use of trademarked terms •requires all headings to be in sentence case •suggests replacements for frequent mistakes @aiven_io ~ @lornajane

Continuous deployment •immediate deploy on merge to main •build static site and deploy •repeat often @aiven_io ~ @lornajane

Open Source Operation @aiven_io ~ @lornajane

Contributors Encourage contributors (internal or external) •well-tended repository •contributor guidelines •office hours for internal contributors •good review practice @aiven_io ~ @lornajane

Maintainers Principle of shared responsibility •reviewer guidelines in the repo •pull requests need a single approver •all git-enabled Aiveners can merge •editorial review is available Gatekeepers have no place in collaboration @aiven_io ~ @lornajane

Engineering Documentation @aiven_io ~ @lornajane

Resources •https://docs.aiven.io/ •https://github.com/aiven/devportal/ •https://lornajane.net •https://docsfordevelopers.com/ •https://idratherbewriting.com/ @aiven_io ~ @lornajane