My 13-year-old daughter and her classmate recently created a math game designed for fifth grade students learning variables. They used Codesters, which is a website that uses Python to let kids code directly in the browser in an easy-to-learn way.
Stack Overflow recently published their 2018 survey, which included more than 100,000 developers. What surprised me most was the lack of diversity in the survey participants.
In the latest episode of the Write the Docs podcast, we chat with Carolyn Stransky, a journalist and JavaScript developer living in Berlin, about ways to humanize documentation. We discuss dilemmas with transparency in docs (the balance between honesty and negativity), ways to avoid gendered language (including whether to correct workplace misuse of "he"), strategies for achieving plain language and clarity (such as by reading your content out loud), the term "user" and alternatives, how to develop empathy for your audience, why terms like "simple" and "easy" are problematic (even in Marketing), tools for identifying insensitivity and complexity in docs (Hemingway, Alex), what makes content sound truly human, and more.
I recently gave a half-day API workshop in Denver on March 10, 2018. Topics in the workshop included how to document reference API content (endpoints, parameters, requests, etc.), what non-reference topics (for example, status and error codes, rate limiting, getting started, sample apps) are common, how to create an OpenAPI specification document and Swagger UI output, and more. You can view a recording of the workshop, browse the slides, and listen to the audio here. Because of the length, the content is divided into three parts.
Last week I ran across an interesting site called DocToolHub that classifies hundreds of tech comm authoring and publishing tools. When I shared the link on Twitter, it received 38 favorites and 16 retweets, so I assume many others found the site useful as well. I decided to follow up with Greg Babb, the person who created DocToolHub, to find out more details and the story behind DocToolHub. I told Greg I was interested in strategies for tagging and classification, as these strategies apply more generally to documentation as well. The following is a guest post by Greg Babb about DocToolHub.
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.
