Technical writers can also deepen the value of the documentation they create by focusing on areas of complexity to users. Complexity not only involves articulating the "string theory" parts of a system but also formulating the content in a way that users, regardless of their level, can understand. The task of simplifying complexity can only be achieved by leveraging many perspectives across groups; thus, focusing on simplifying complexity will also achieve goals around enabling information flow and improving the customer experience.
Content experience — influencing the content across all touchpoints in the customer's journey — is another area where tech writers can add more value. This roots the tech writer's contributions in content development activities, not merely information flow. However, given the expanded bandwidth that cross-functional contributions require, these efforts require backing from customer satisfaction groups in the organization. Additionally, despite the good fit of docs to influence the customer experience, companies still primarily want someone to write clear docs, not necessarily someone to address the customer experience.
Technical writers can add more value by encouraging information flow across disparate groups within an organization (such as Support, Engineering, Marketing, Training, Field Engineering, and more). Encouraging information flow not only empowers these groups with better knowledge, it also encourages them to share feedback and input that dramatically improves the documentation. However, information flow alone is too tenuous of a value to attribute to technical writers, and probably only applies to large organizations.
Documentation is valuable. It derives this value not from a carefully measured financial ROI, which is impractical to measure, but from the perceived value by the many groups within the company that use the documentation. But even though documentation has value from perceived usage, it might not have more value relative to other organizational resources that are also used by the same groups. As such, arguments about value based on usage fall short. Tech comm must seek for additional forms of value to tip the balance.
Before jumping into the value debate, I want to review some of the research that has been done previously. With this topic, the STC's academic publications have a rich history of study and exploration.
In this essay, I explore arguments for the value of documentation and technical writers in an organization. Although metrics usually fall short as a way to measure value, documentation's value can be established in part through usage. Technical writers can also contribute value by enabling information flow, influencing the content touchpoints along the user's journey, and by simplifying complexity for users.
TC Camp 2018 is just around the corner (Jan 26-27, 2018). Liz Fraley started the TC Camp unconference out of a growing dissatisfaction with other conferences. She modeled TC Camp after another camp that was low-cost, run by a non-profit, and intended to better the community. TC Camp's popularity arises from its unconference format — it places more focus on the attendees instead of juried presentations. As long as you participate, vote, and interact in the discussions, you're guaranteed to connect.
In this episode, we chat with Eric Holscher (WTD cofounder) and Mikey Ariel (WTD Europe organizer) about the Write the Docs community itself, including origins, founding ideas, goals, challenges, trends, and roadmaps for the community. We dive specifically into idea of diversity of roles (and the term 'documentarian'), the way open source principles inform the community's core values, balancing individual freedom to contribute on one's own terms with the expectations of the WTD experience, and more.
Voracious reading begins with voracious thinking. Asking questions gives us a purpose and drive for reading.
In this episode of the Write the Docs podcast, we chat with Kadir Topal, product manager for Mozilla Developer Network Web Docs project, about how they manage their large body of documentation for web developers. The MDN project provides standards-based documentation around web development topics (for example, HTML, CSS, and JS) intended for web developers, with the goal of producing consistent experiences for users across web browsers. Kadir gives us an inside look into the challenges, goals, and roadmap with this project.
When you don't have a system that logs users in and tracks their progress, it can be a challenge to show their progress in a course. However, rather than showing progress through completed pages, quizzes, or other interactive exercises, progress can also be measured through larger user goals that extend beyond the course. In the case of my API documentation course, the user's goal is to break into the field of API documentation, not so much to finish a course. Breaking into API documentation requires users to build a compelling portfolio, which is how I'm choosing to measure the user's progress.
In the Publishing your API documentation section of my API documentation course, I recently added a new topic called "Case study: Switching tools to docs-as-code". In this article, I dive into a lot of challenges, decisions, and other details we faced in converting to the docs-as-code model, especially when publishing the output directly from the server.
I recently gave a presentation titled "Introduction to API Documentation" to the STC Silicon Valley chapter in Santa Clara, California. The video recording and audio are available here.
Writing is an activity that is best balanced with equal measures of editing and learning. Overdoing any one activity can lead to exhaustion and burnout, but by balancing these three activities — writing, editing, and learning — you can switch to different neural muscles and find more energy in the long-term.
I added a new tutorial on creating an OpenAPI 3.0 specification document in my API course. (OpenAPI was formerly referred to as Swagger.) The tutorial has 8 steps and guides you through the process of creating the specification document in the context of a sample weather API. Additionally, I explain how the specification fields get displayed in Swagger UI. Swagger UI is the display framework that reads the OpenAPI spec and generates an interactive documentation website.
