Podcast 104 - Fixing broken developer portals, in Ellis Pratt's Cherryleaf podcast, is well worth listening to. Ellis explains a strategy of analyzing developer portals by looking at the developer journeys within the portal and identifying gaps or friction points in that journey.
In my API course, I defined intake processes for large documentation projects and small requests. However, I recently realized a major flaw in the process for small doc requests -- who can make the documentation request. In a nutshell, if you let anyone make doc requests, you can end up saddled with tasks to create documentation for which you lack information. If you instead require product teams to make the requests, you're more likely to get the information you need upfront.
During my transition time between Amazon and Google, I decided to create a brief list of some good decisions and minor mistakes during my five years at Amazon. This is a brief list, without much elaboration, but I think it's still valuable.
I recently published a comprehensive checklist for evaluating documentation quality (the section starts here). In this section, I noted that my perspective is more evolving and experiential, which was good to note because when I tried to actually use the checklist, I realized a few shortcomings that I needed to address. Here are my 10 observations.
Recently I received feedback from someone saying that they couldn't tell when my API documentation quality checklist article was published. This was embarrassing to me because printing timestamps on pages was one of the quality characteristics in the checklist. So I decided to add last-modified timestamps to every page. Unfortunately, this is a much harder task than it initially seems.
I recently re-wrote the article about product overviews in my API docs course, giving the article much more depth and discussion. I also included a survey to gather your feedback about my viewpoints with the product overview.
A few years ago, I posted an article about Xeditor titled Xeditor, a CMS editor for XML content. In this post, I follow up about Xeditor with a Q&A with the founder, Matthias Kraus. The exchange here goes in-depth about Xeditor's origins, audience, latest enhancements, roadmap, and more.
Write the Docs Podcast episode 33 is available. In this podcast, we chat with Anton Bollen from Techsmith about using simplified user interfaces with screenshots. A simplified user interface reduces the unimportant elements so the user's attention focuses only on what matters.
At the beginning of each year, I update my site analytics information (pulled from Google Analytics) and analyze traffic trends, user data, and any other information for my site. These analytics sometimes influence what I focus on for the upcoming year. This year, not much changed in terms of site analytics (which is a good thing). I also have a few simple thoughts on the year ahead.
I recently added a much-needed topic in my API course: a list of criteria for assessing API documentation quality. This list has 80 characteristics sorted into the following categories: Findability, Accuracy, Relevance, Clarity, Completeness, and Readability. I also describe ways to score and assess the docs for quantitative measurements.
Ellis Pratt's latest episode of Cherryleaf lists goals that technical writers have for 2021. Rather than just listing each response, Ellis reads these responses while walking in some historic setting and peppers in historical asides to break up the responses.
Many people and companies are moving out of California right now. For example, Tesla, Oracle, HP, Palantir, and others are moving headquarters to other locations (mostly Texas), as are many tech workers. Reasons for the migration include high state income taxes, government regulation, constant fires, and more. Also, the high cost of living is hard to justify during the work-from-home model of the pandemic. You can read many articles about an exodus from Silicon Valley. This post isn't about the merits of California but is instead a more personal post about moving to Seattle and how to look at areas virtually. When you're moving and trying to decide about locations, can you make informed decisions using virtual tools alone? These tools could include mapping tools as well as VR tools that offer immersive street views of the areas. What information can't you gather through virtual explorations of an area?
I recently switched jobs from Amazon to Google. I'm still in the Bay area right now, but in a couple of weeks I'll be relocating to Seattle. I had been at Amazon in Sunnyvale for nearly 5 years and was ready for a change. Plus, I've always been captivated by the ambitiousness of Google. I will continue to post regularly on my blog and API course. Just a reminder: my views are always my own and never any representation of a company. I'm excited for the upcoming challenges and other new encounters at Google. I like experiences that reshape my thinking processes, invite me to try new things, and present challenges to overcome.
Larry Swanson, a UX content strategist, runs a podcast called Content Strategy Insights. Larry recently interviewed me a few weeks ago about various topics related to API documentation.
A couple of years ago, I was chatting with a local tech writer at a WTD meetup, and he mentioned that while he enjoys my posts on tech comm, he wished I would post more about biking in the area. This surprised me because I didn't really think anyone read or cared about my biking posts. Since his note, I admit I haven't posted anything about biking for a while. I did compile my previous posts about biking into a sidebar for easier navigation, but I failed to follow through with more biking posts. Today I hope to remedy that by sharing the best biking route in all of Santa Clara! I call this the Santa Clara loop.
