I recently gave a presentation called "Publishing tools for API documentation" to the Write the Docs South Bay meetup group on January 18, 2018. You can view a recording of the presentation, browse the slides, and listen to the audio here.
I usually start the beginning of the year by reviewing metrics for the previous year. These metrics help me better understand my readers, the trending topics and issues, and other points of interest. In 2017, my site averaged 2,300 page views a day. The average reader is a 30-year-old female living in New York using Chrome on a Windows PC who identifies as a technophile. Looking at the metrics, I had some unexpected realizations. First, these topics seem to emerge as the most popular: Swagger, agile, quick reference guides, trends, plain language, and tech writing careers. Longer posts, usually 1,600+ words, are more frequently read. Titles with words that include "fail" or "realizations" or "limits" or other contrarian triggers get more reads. Social media traffic is small compared to organic search. And finally, no common narrative pattern emerged in the posts other than a simple relevance technique in the intro, which I usually always start with.
I published an article in the most recent issue of STC's Intercom magazine titled "How to Research What You Need to Learn to Be Successful as a Technical Writer" (Nov/Dec 2017). The article explores the approach I take in "researching" topics at work to gather the information needed for documentation.
Looking at technical writing trends is always a popular topic. Now that 2017 is wrapping up, let's review some tech comm highlights for the year and outline some trends in technical communication for 2018.
It's time to wrap up this essay with some concluding thoughts and takeaways. I also list the references here for more reading.
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.
