Reducing the complexity of technical language (new article in Simplifying Complexity series)
I added a new article in my ongoing series about simplifying complexity. The article is called Reducing the complexity of technical language and explores reasons why the language in technical documentation tends become so full of jargon and other unfamiliar terms, and a few solutions for simplifying the language. I emphasize the need to read the competitor's documentation and other articles in the industry to get a sense of the right terms and contexts that users likely expect. I also decided to read the article for those who prefer podcasts.
Random reflections on the throwaway mentality in our culture
When should you fix a broken process and when should you simply throw it away? Sometimes we continue on within broken processes for years; it might make sense to systematically try to fix broken processes — to a point.
Thoughts on docs-as-code after 3 years -- it works!
I've been quite happy with our current docs-as-code implementation. It's worthwhile to periodically reflect why the docs-as-code approach tends to work so well.
A short survey to measure academic/practitioner attitudes
The following two surveys will capture the thoughts and attitudes that Tech Comm practitioners and academics have towards each other as members of the same field. The survey takes approximately 1 minute to complete and consists only of 7 selections about whether you agree or disagree (along a scale). Your answers are anonymous. The responses here will be compared to a similar survey administered at a later time.
10 ways technical writing is just like the World Cup
I don't usually watch soccer, but I do get drawn into the World Cup. And this year, I'm finding that there are a surprising number of similarities between the World Cup and technical writing. Yes!!! So let's get started with the top 10 ways that technical writing is just like the soccer at the World Cup.
MadCap Flare 2018 and MadCap Central Review for the May 2018 Release -- Guest post
The following is a guest post from Una Cogavin, a certified MadCap Advanced Developer and Flare consultant. In this post, Cogavin reviews Flare 2018 and Central and explains the features she finds most useful in these tools.
Evaluating the user experience of documentation -- Podcast with Bob Watson
This week I chatted with Bob Watson, an assistant professor of tech comm at Mercer University, about how to evaluate the user experience of documentation. The idea of doing a podcast came up during a comment thread on a previous post about reconstructing the absent user. We had a long exchange in the comment threads and thought it would be good to have a podcast about the topic.
Non-Reference Content section updated in API course
I updated and reworked the topics in the Non-Reference Content section in my API doc course. This section includes the following topics: API overview, Getting started, Authentication and authorization, Status and error codes, Rate limiting and thresholds, Code samples and tutorials, SDKs and sample apps, Quick reference guides, API best practices, and Glossary. These sections are important in API documentation but tend to be overlooked as most discussions around API documentation focus on endpoint documentation only.
Hiding Complexity -- A new Simplifying Complexity article
New article in Simplifying Complexity: Reconstructing the absent user
I have a new article in my series on Simplifying Complexity. This article talks about why reconstructing the absent users is essential to creating good documentation.
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.