Engineering Documentation • Lorna Jane Mitchell • YOW! 2022

This presentation was recorded at YOW! 2022. #GOTOcon #YOW https://yowcon.com Lorna Jane Mitchell - Head of Developer Advocate at Aiven & Writer for a Number of Outlets @LornaMitchell RESOURCES https://docs.aiven.io https://github.com/aiven/devportal https://docsfordevelopers.com https://idratherbewriting.com Lorna https://lornajane.net https://twitter.com/lornajane https://github.com/lornajane https://linkedin.com/in/lornajane ABSTRACT 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. [...] TIMECODES 00:00 Intro 01:39 What engineering is about 03:34 What documentation is about 04:57 Colleague enablement 07:38 Diataxis 09:12 Style guide 10:46 Content structure 12:49 Docs as code 14:32 Source control 17:00 Text-based markup & diagrams 22:22 Tooling 26:43 Automating a docs platform 27:04 Continuous integration 30:04 Vale 34:26 Continuous deployment 35:54 Open source operation 36:37 Contributors 38:27 Maintainers 40:36 Engineering documentation 41:33 Resources 42:14 Outro Download slides and read the full abstract here: https://yowlondon.com/2022/sessions/2333 Kevlin Henney • 97 Things Every Programmer Should Know • https://amzn.to/2Yahf9U Henney & Monson-Haefel • 97 Things Every Software Architect Should Know • https://amzn.to/3pZuHsQ Matthew Skelton & Manuel Pais • Team Topologies • http://amzn.to/3sVLyLQ Michael Jackson • Software Requirements and Specifications • https://amzn.to/3ql2T14 Geoffrey West • Scale • http://amzn.to/3eKMbpc Donald G. Reinertsen • The Principles of Product Development Flow • https://amzn.to/3hJ2Ye2 https://twitter.com/GOTOcon https://www.linkedin.com/company/goto- https://www.facebook.com/GOTOConferences #EngineeringDocumentation #Documentation #Diataxis #Automation #CICD #Vale #Teams #Team #ColleagueEnablement #SoftwareEngineering #Programming #LornaJaneMitchell #Aiven Looking for a unique learning experience? Attend the next GOTO conference near you! Get your ticket at https://gotopia.tech Sign up for updates and specials at https://gotopia.tech/newsletter SUBSCRIBE TO OUR CHANNEL - new videos posted almost daily. https://www.youtube.com/user/GotoConferences/?sub_confirmation=1