In my 2018 trends post, I mentioned that I plan to give some attention to TC academic/practitioner attitudes, opportunities, and interactions. I have a larger project in mind that involves changing attitudes, which I'll expand on in the future. However, for now I need a baseline starting point to measure against later.
Previously, I explored the use of embedded maps to help guide users through larger processes. But all the maps I showed were linear maps. What about maps for non-linear, complex systems? In the Simplifying Complexity section of my site, I added a new tutorial for navigating through more non-linear, complex spaces. The strategy involves tagging content with metadata so that it can be surfaced to the users in the right context.
In an earlier post on value arguments for tech comm, I mentioned that in 2018, I plan to explore some innovative ways to simplify complexity so that I can deepen the value I provide to users. To host this content, I created a new section on my site called "Simplifying Complexity." So far I've added just one topic there on navigation maps. In the topic, I argue that by allowing users to toggle between micro and macro views of a system, often through embedded workflow maps, you can help users better understand and orient themselves in complex systems.
In this episode of the Write the Docs podcast, we chat with Abhinav Asthana (founder and CEO of Postman) to discuss how Postman, a REST client, can be used to create, collaborate, and publish API documentation.
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.
