Developer portal strategies for complex landscapes -- conversation with Kristof van Tomme
Recently I chatted with Kristof van Tomme, CEO and co-founder of Pronovix, about a topic that's become increasingly relevant in the past several months: how to deal with complex, rapidly evolving landscapes. Specifically, we focus on developer portal strategies that involve finding a balance between constraints and flexibility. Too many constraints reduces your ability to adapt to uncertain changes that might require innovative, unknown solutions. Too much flexibility might not lead to any coherent, overarching story about how to use your APIs in an integrated way toward a business goal.
What makes a good covid sign?
Have you noticed lately that there are a million new signs everywhere providing instruction about how to act due to Covid19? The different approaches in these signs makes them interesting to analyze. I took a few pictures the other day of signs I saw on my hike near Rancho San Antonio, a stop at Trader Joe's, and then a trip to my local park. I thought it would be fun to write a post critiquing the different approaches and to arrive at a conclusion about what makes a good Covid sign. Do the same principles behind a good sign also apply to UI text?
Treat code like code and prose like prose
Some recent experiences have prompted me to rethink the value of treating docs like code in some respects. I want to return to focusing more on content rather than technical workflows, especially when creating new content. Some of the docs-like-code processes exclude too many people in non-engineer roles who would otherwise contribute to the review and development of the content.
Diversity in tech comm -- Conversation with John Paz
In this conversational Q&A post, I chat with John Paz, a senior content designer for Atlassian, about diversity in tech comm. It's well known that the tech industry, particularly in Silicon Valley, struggles to live up to its ideals about diversity. The employee demographics at most tech companies don't reflect the same demographics of their surrounding communities. Even when minorities are hired, promotions and leadership positions within the company are another roadblock. John gives us his unique insight into the diversity issue, specifically focusing on tech comm and his experiences both in the Bay area and elsewhere.
What's the point of site search?
Lately, I've been researching different options for doc search. I've lived for years with poor search in my docs, and I haven't paid a lot of attention to it. Search is one of those elements that's easy to ignore. Despite how easy it is to ignore search, search is one of the most common user behaviors, and one that most tech writers would consider to be important. So let's examine that paradox a bit more — how can search be so important and unimportant at the same?
Making a comfortable office environment when working from home is harder than it seems
We recently moved about a mile away to a larger house (still renting, not owning), and this house has an office. I was initially excited about working in the office, and I still am, but I've come to realize some challenges in getting a comfortable office environment. It's harder than it looks. When I would go to work each day at my corporate office space, I now see that I took many details provided by facilities for granted. Here are some challenges that I have had to overcome to make my home office comfortable.
API the Docs recording: How Trends in API Documentation Differ from other Tech Comm Trends
I recently presented a session at the API the Docs virtual series on Wednesday, May 27, 2020, as part of the 5th edition. My session covered dev doc trends, and another session covered API design. A recording of my presentation is available below.
WTD Australia event recording -- 'Remote discussion: Techcomm in the times of pandemic'
Guest post: Why are technical writers often treated as such an unimportant part of a company?
A reader whose company recently laid off two-thirds of their tech pubs staff asked why technical writers are often seen as unimportant in a company. I asked Jeremy Rosselot-Merritt, an academic at the University of Minnesota who has been doing research into tech comm value in the workplace, to respond to the reader's question.
Results of Pandemic Impact on Tech Comm survey
The results of the Pandemic survey are available here. The survey is still open, but with 230 responses, I'd like to describe a few highlights and thoughts about it.
"Building Great Documentation" -- WAPI FM radio hour
I recently participated in an online radio-style chat about documentation with the folks at Readme.com. In an ambitious undertaking, Readme created a 24-hour streaming radio show (called "WAPI FM"') focused on APIs, from March 26-27, 2020. They are publishing some of the recordings week by week. During this hour, Ryan Openshaw and Greg Koberger chatted with Andrew Baker from Twilio and me about a host of documentation topics.
Short survey about quarantine/pandemic impact on tech comm
I'm curious to know how the quarantine/pandemic is affecting tech comm. I created a short survey to gather some insights about possible trends. It's unclear how tech comm will play out — there could be gains in places and losses in others.
Connecting micro content with search analytics -- notes on the first MadCap Flare and MadCap Central 2020 Release
MadCap Software's 2020 release for MadCap Flare and MadCap Central include significant enhancements to micro content, code syntax highlighting, privatized output, and more. Through search analytics in MadCap Central, if you identify search phrases, and search phrases that return no results, micro content can be created to address these gaps, making your content much more discoverable for your users.
A user manual for your death?
This is a gloomy topic but one that until recently I'd never even considered. When you die, what "user manual" will your family members follow to carry out tasks that need to be done? About two years ago my father passed away, and while it was emotionally difficult, I realized that figuring out the logistics of one's passing was also challenging. In preparing for the worst with the Coronavirus, I started to think about what needs to be done in case I die. (Of course, I hope this doesn't happen, and I'm not sick or anything. I'm just thinking ahead to worst-case scenarios.)
API doc course update: Re-architecting the OpenAPI spec tutorials to start with visual modeling tools first, then code
One of the most challenging aspects of my API documentation course is with the OpenAPI specification. Describing how to code this detailed spec line-by-line is not only tedious but highly prone to error, confusion, and frustration. Recently, I decided to shift the approach in my course to begin first with coding the OpenAPI spec in a visual editor using Stoplight Studio, and then later, if desired, transition to a code-based approach.