Erik Rask (M.Sc. Computer Science and Engineering) is currently working on information architecture and customization at Paligo. He has been creating technical user guidance in the networking industry for almost twenty years, from content production through product/UX testing and information architecture, to DevOps-based systems development for technical content production in agile development teams.
Always be Documenting: Effective Technical Writing in a Continuous Integration (CI) Environment
Documentation for continuous integration (CI) can be a culture shock for technical writers. Often, documentation is a fixed process where outputs are built in proprietary tools and created “after the fact,” i.e. too late to “wow” and properly support users. Adding to the challenge, technical writers are often expected to adapt to the developers world rather than the other way around. This is a challenge particular to those who work in software products, as they have to try to align with different product creation methodologies such as “agile”, “lean” or “continuous delivery” – and even harder, they have to let go of perfection as there really is no final version in an iterating product. Technical writers need to move to modular content creation (i.e. topic-based structured authoring), and utilize automation processes from the DevOps world to enable their documentation to deliver to the end user on an hourly or daily basis.
This talk aims to show you how to create your documentation to align with a CI working environment without bugging the engineers too much! Get hold of important metadata available in software code through the mechanisms already used in many DevOps departments. Through a real-world example, we show you how a definition language for configuration data is converted by means of a CI pipeline into a format importable to most technical writing tools. At the end of it, you will stand better equipped to collaborate with your DevOps colleagues on content that can help streamline your writing workflows significantly.