Adobe FrameMaker

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Adobe FrameMaker

Latest Posts

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.
Upcoming presentation in Denver: Docs-as-code tools and workflows (March 9, 2018)
I'm giving a 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'll 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. The presentation will include a number of concrete examples and demos.
Upcoming API workshop in Denver (March 10, 2018)
I'm giving a half-day API workshop in Denver on March 10, 2018. Topics in the workshop will include reference API content (endpoints, parameters, requests, etc.), non-reference topics (status and error codes, rate limiting, getting started, sample apps), creating an OpenAPI specification and Swagger UI output, and publishing tools for API docs (such as static site generators, hosted API platforms, and more).
Upcoming STC San Francisco presentation: Beyond mere endpoint reference — the overlooked content in API documentation (Feb 21, 2018)
I'm giving a presentation to the STC San Francisco chapter called "Beyond mere endpoint reference — the overlooked content in API documentation" on February 21, 2018.
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.
Part VII: Conclusion (Value arguments for docs and tech comm)
It's time to wrap up this essay with some concluding thoughts and takeaways. I also list the references here for more reading.

subscribe via RSS