I recently gave presentation to the Rocky Mountain STC on "Docs-as-code workflows and tools" on March 9, 2018. The docs-as-code approach is most common in the developer doc space. In this presentation, I explore the upsides and downsides of treating documentation as software code, and what details are involved in adopting engineering tools, workflows, collaborative processes, and other practices. You can view the recording, listen the audio, and browse the slides here.
I recently gave a presentation to the STC San Francisco chapter called "Beyond mere endpoint reference — the overlooked content in API documentation" on February 21, 2018. You can browse the slides and listen to the audio recording here.
In the Simplifying Complexity section of my site, I published a new article about how to ensure information harmony across a larger documentation landscape, where other articles might contain similar themes and information. In the article, I dive into two factors that increase complexity in a system: specialization and interconnectedness. Relevant to documentation scenarios, when subject matter experts contribute specialized articles into a larger system without understanding how their individual article interacts with other information in the system, the result is often a redundant, contradictory, and ever-increasing jumble of content. In this article, I explore ways to solve this problem through better metadata, primarily evaluating tags and whether they can help identify all known instances of content. You can read the article here: Ensuring information harmony in the larger documentation landscape.
With the beginning of the 2018 STC elections, I decided to ask the Vice President candidates a few questions to get to know their perspectives on tech comm. The elected VP automatically transitions into the president role the following year after election, so it's an important voting decision. I asked both Pam Brewer and Ben Woelk the same questions. The following are Pam's responses. (You can read Ben's responses here.)
With the beginning of the 2018 STC elections, I decided to ask the Vice President candidates a few questions to get to know their perspectives on tech comm. The elected VP automatically transitions into the president role the following year after election, so it's an important voting decision. I asked both Ben Woelk and Pam Brewer the same questions. The following are Ben's responses. (You can read Pam's responses here.)
I recently gave a presentation to the STC San Diego chapter and WTD San Diego group called "Swagger UI and the OpenAPI specification" (February 13, 2018). You can view a recording of the presentation, browse the slides, and listen to the audio here.
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.
