The reason I always find time to write on this blog
I finally realized why I write so much: because not writing tends to be deflating.
Stoplight -- creating a single source of truth to drive the API lifecycle
Stoplight provides a platform with visual modeling tools to create an OpenAPI document for your API -- without requiring you to know the OpenAPI spec details or code the spec line by line. This API specification document can act as a single source of truth that empowers the whole API lifecycle, from UX prototyping to testing, development, documentation, sales, and more.
My site now has Algolia search integrated
You might have noticed a new search box on my site. My new search integrates Algolia's search service, replacing the Google Custom Search Engine I previously had. While Google Custom Search Engine was good, it draws people away from my site and more into the general web. There are tradeoffs to both Google Custom Search and Algolia.
Replaced the previous weather API example in my API course to now use OpenWeatherAPI
I updated the sample weather API in my API course to use a more robust and stable weather API from OpenWeatherMap. Any time you incorporate free or open-source projects, you run the risk that the code won't be supported in the long term.
Do you have to relocate to an urban tech hub to find a technical writing job?
To find high-paying jobs in tech comm, many technical writers move to urban technology hubs because companies want their workers on site. Living in an urban tech hub usually involves high costs of living and the sacrifice of a more rural, suburban lifestyle. It's unclear why the digital revolution doesn't motivate more companies to welcome remote workers.
Strategies from pickup basketball -- Why you shouldn't guard the worst player or focus too much on the documentation no one reads
Most of my readers are technical writers, so I rarely post about basketball. But given the current NBA playoffs, I'd like to briefly explain my latest pickup basketball strategy and how it can help you win not only on the court, but on documentation projects too.
New Simplifying Complexity article on shaping information into familiar schemas, especially story
In case you haven't been following previous posts, I have a microsite called Simplifying Complexity where I'm exploring various approaches for making complex information more usable and consumable. This microsite contains longer, more in-depth articles following a specific theme. My latest addition to the site is a new article called 'Reducing complexity by shaping information into familiar schemas, especially story'.
A Review of the MadWorld Conference -- guest post by Jayna Locke
In this guest post, Jayna Locke explains what brought her to the MadWorld Conference the first time and what keeps her returning. She describes the main reasons for attending, tips for getting the most out of the conference, best practices, and more. The MadWorld Conference takes place June 3-6, 2018 in San Diego, California.
New article on Simplifying Complexity: Reduction, layering, and distillation as a strategy for simplicity
I published a new article on Simplifying Complexity called Reduction, layering, and distillation as a strategy for simplicity. It's all about how reduction and distillation of information helps reduce complexity for users.
The math game my daughter and her friend created with Codesters
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.
What can we learn from the homogenous profiles in the Stack Overflow 2018 survey?
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.
WTD podcast episode 14: Humanizing your documentation
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.
Recording of API documentation workshop in Denver
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.
Guest post: The story behind DocToolHub, a site for finding tech comm tools
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.
Recording of Docs-as-code tools and workflows presentation
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 the audio, and browse the slides here.
subscribe via RSS
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.
