Engineering Documentation

A presentation at YOW! London in November 2022 in London, UK by Lorna Jane Mitchell

Slide 1

Slide 1

Engineering Documentation Lorna Mitchell, Aiven

Slide 2

Slide 2

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

Slide 3

Slide 3

Documentation enables customer success @aiven_io ~ @lornajane

Slide 4

Slide 4

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

Slide 5

Slide 5

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

Slide 6

Slide 6

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

Slide 7

Slide 7

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

Slide 8

Slide 8

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

Slide 9

Slide 9

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

Slide 10

Slide 10

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

Slide 11

Slide 11

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

Slide 12

Slide 12

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

Slide 13

Slide 13

Automating a docs platform @aiven_io ~ @lornajane

Slide 14

Slide 14

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

Slide 15

Slide 15

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

Slide 16

Slide 16

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

Slide 17

Slide 17

Open Source Operation @aiven_io ~ @lornajane

Slide 18

Slide 18

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

Slide 19

Slide 19

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

Slide 20

Slide 20

Engineering Documentation @aiven_io ~ @lornajane

Slide 21

Slide 21

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