Recording of STC San Francisco presentation: Beyond mere endpoint reference — the overlooked content in API documentation
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.
New article in Simplifying Complexity -- Ensuring information harmony in the larger documentation landscape
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.
Perspectives on tech comm from the VP Candidates — Q&A with Pam Brewer
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.)
Perspectives on tech comm from the VP Candidates — Q&A with Ben Woelk
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.)
Recording of OpenAPI and Swagger presentation (for STC and WTD San Diego)
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.
Two open-ended surveys to gauge practitioner/academic attitudes
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.
New Simplifying complexity tutorial: Discoverability through metadata
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.
New section on my site: Simplifying complexity
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.
WTD Episode 13: Postman for API development and docs — Interview with Postman Founder
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.
Recording of WTD South Bay presentation: Publishing tools for 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.
Unexpected realizations after a comprehensive review of my 2017 site metrics
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.
New STC Intercom article: How to Research What You Need to Learn to Be Successful as a Technical Writer
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.
What technical writing trends will we see in 2018?
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.
Value arguments for docs and tech comm (Part VII)
It's time to wrap up this essay with some concluding thoughts and takeaways. I also list the references here for more reading.
Value arguments for docs and tech comm (Part VI)
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.