Write the Docs Podcast Episode 33: Simplified user interfaces, with Anton Bollen
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.
Site analytics for 2020 -- trends, reflections, and thoughts
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.
Measuring documentation quality -- a rubric for developer docs
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.
Cherryleaf collects tech writer goals for 2021
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.
Moving to Seattle and making housing decisions using virtual tools
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?
Job transition: from Amazon to Google
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.
Content Strategy Insights podcast with Larry Swanson about API documentation
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.
The most perfect 20-mile biking loop in Santa Clara
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.
Finished up the section on documentation processes (for now)
I finished up the documentation processes section in my API course that I've been adding to over the last couple of months. Here's a list of all the article in this section.
New API course article: Processes for changing internal doc culture
I added a new article in my API documentation course about processes for changing internal doc culture. One of the most influential aspects that will determine your experience as a technical writer is the company's documentation culture and environment. If you find yourself in an organization with a poor documentation culture, it can be difficult if not impossible to change it. Poor documentation culture/environments lead to a high turnover on doc teams, loss of motivation for existing writers (especially as their colleagues constantly leave, which increases the workload), and contributes to a downward spiral of tasks you can never quite get a handle on. In this topic, I outline six strategies you can implement to influence change in your company's documentation culture.
New API course article: Processes for external contributors
I added a new article to my API documentation course on processes for external contributors. One of the main advantages of a version-control-based system, especially using open-source technologies, is the promise of collaboration. Not just collaboration with your immediate team, but scaling beyond your team to also include other contributors within your organization and even contributors from the community. Many people embrace docs-as-code with the hope and expectation that many engineers will contribute to the docs. In this section, I cover processes to consider when external contributors (external to your team, not necessarily external to the company) write content.
Documentation templates and The Good Docs Project -- guest post by Ankita Tripathi
Documentation templates not only help teams align with consistent approaches in docs, templates help guide engineers, non-writers, or other roles in creating content, removing the intimidation of a blank page. A group of writers passionate about templates have been working together to create templates for a variety of documentation scenarios. This group's project is called The Good Docs Project. The project makes available templates for API overviews, quickstart guides, reference, how-to topics, discussions, tutorials, and more. The following is a guest post by Ankita Tripathi, a member of The Good Docs project, discussing the project and her motivations for getting involved.
The story behind Document360 -- podcast with founder Saravana Kumar
In a previous post, I explored how Document360, a new cloud-based documentation platform, handles API documentation scenarios. This time, I decided to record a podcast with Saravana Kumar, founder of Document360, to get the behind-the-scenes story about how Document360 came about, what's driving their fast pace of development, and their roadmap for the future.
Process for collecting feedback post-release (new article in API doc course)
I added a new article covering the process for collecting and addressing feedback post-release in my API doc course. Collecting feedback post-release involves a host of new challenges and processes, such as how to optimize your feedback form, how to account for random externally driven requests across your dev portal, how to process the feedback from incoming requests, and so on.
How does Document360 handle challenges with API documentation?
How does Document360 handle some of the tooling tasks common with API documentation? In this post, I look at some sample API doc sites using Document360 and look at how they handle aspects such as collaboration, GitHub integration, search/findability, versioning, OpenAPI integration, code-syntax highlighting, context-sensitive help, and developer portal architecture.