A presentation at YOW! London in in London, UK by Lorna Jane Mitchell
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
Every technology is made better and more delightful when it has excellent documentation, but producing the documentation can be a painful process. In this session you will learn how to borrow what you know from good engineering practice and apply it to creating great documentation. Using docs-as-code for simple change management, pull request workflows for familiar and powerful collaboration and build previews, and CI to ensure quality by checking the prose and formatting, we will cover how to make documentation projects a fun place to work. Best of all, we’ll look at what makes great documentation for engineers, and how we can supercharge the developer experience for our users. This session is recommended for anyone who wants to make sure that technical users can build great things, and wants to use the best of their existing toolchain to do it.
