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.
Techwriter.pl is an online hub of information for technical writers in Poland. Although it's maintained by volunteers, the site continues to thrive from its inception in 2013 up through today. The following is a guest post by Michal Skowron and Jakub Wisniewski, two Poland-based technical writers who helped shape Techwriter.pl and who wanted to tell the story of the site.
Finding the right software tools to write API docs is a constant and difficult challenge given the wide variety of tooling and environments in the developer doc space. However, if your goal is to break into developer documentation (rather than specifically reworking your company's documentation tools), you would be better off deepening your technical background with programming languages rather than focusing on doc tools.
About Tom Johnson
I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out my API documentation if you're looking for more info about that. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.