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.
In this episode of the Write the Docs podcast, we talk about what's going on in our lives as documentarians and product owners. We don't have special guests during this episode. Instead, we discuss challenges we're facing and any interesting aspects of our documentation lives.
When documenting REST APIs, the OpenAPI specification (formerly called Swagger) is pretty much the default standard. Yet learning the OpenAPI spec is not a trivial undertaking and requires significant ramp-up. SwaggerHub is a tool can reduce the complexity in creating your OpenAPI spec file because it enables collaboration between both developers and technical writers. This collaboration not only helps compensate for gaps in understanding with the spec, SwaggerHub also offers many other features (such as versioning, content re-use, inline commenting, and more) to make the authoring and publishing experience easier.
