Writing for Developers: Take your Project Docs to the Next Level
Conference: KubeCon + CloudNativeCon Europe 2021
Authors: Celeste Horgan
Summary
The talk is about how to approach writing for developers and take project documentation to the next level. It emphasizes the importance of documentation in open source projects and how it can meet user needs. The hero's journey is used as a framing device to explain how to write good docs from the user's perspective.
- Great documentation and community support are key when choosing an open source project to use in production.
- Documentation maintenance is important in open source projects as there is no dedicated support team, sales team, or technical writers.
- The hero's journey is a useful framing device to explain how to write good docs from the user's perspective.
- Users always have a goal and understanding that goal is the first task in writing documentation.
- Documentation can meet user needs such as evaluating new tech stacks, learning, supporting existing systems, and developing new features.
- Concept topics briefly describe or link to other topics related to the feature at hand and describe why a user might care about a feature or what the common use cases for using something are.
- Task topics explain how to use a feature to accomplish a goal and can include information about potential pitfalls.
- Reference topics show all the things that a feature can do and help users decide which functionalities to use to solve their problem.
- Good documentation is well-organized, searchable, and explains concepts, tasks, and references.
- Documentation can explain anything by using these three styles of writing: concept, task, and reference.
Abstract
As maintainers know, when choosing an open source project to use in production, great documentation and community support are key. Yet they often struggle with creating and maintaining documentation because of lack of time and skill. This talk, delivered by one of CNCF’s full-time technical writers, will teach you how to approach writing for developers. We’ll go over deciding what to write, thinking about documentation from a user’s perspective, and what makes great writing. We’ll walk through improving an existing page of documentation on an actual CNCF project(*), as well as how to draft new feature documentation from scratch. This talk is aimed at developers who would like to write better, and folks considering a career switch into technical writing. (*) Project TBD.
Materials:
Tags: