I added an article called 'Developer experience (DevX) usability' to my API doc course. Usability can be roughly divided into at least three different areas: (1) Usability with physical products, (2) Usability with code products, and (3) Usability with documentation. Few usability researchers venture into usability with code products because it’s much less clear how to assess the usability of code. But make no mistake, usability is just as much in play with code products for developers as with physical products or products with GUIs.
The other week I was trying to get a better grip on work-life balance. For me, the key challenge was that, without a commute and being at the office, there wasn't a clear separation between work and home. As the result, the two began to blend together. I spent a few weekends working off and on between family and football, and I felt like I needed to change things. To try to fix this and create a more firm separation between work and home, I decided to take my virtual office to a nearby park and work there all day, simulating being at the office. Then at 5 pm I planned to return home, hoping it would have the same effect as if I'd been at the office all day. It didn't go as planned, but not for reasons I thought.
I recently participated in an upcoming Coffee and Content webinar called Treat Code Like Code; Treat Prose Like Prose on September 24, 2020, with Scott Abel and Casey Jordan. A recording of the video is now available.
Conducting a successful documentation review is challenging, especially with developer docs because the content is often highly technical and requires a lot of engineering input and review. At the same time, getting this engineering input and review doesn't come easy. In this new topic in my API course, I outline a tactical approach to conducting doc reviews for large projects.
Last Monday was one of my lowest days of the pandemic. The wildfires burning up and down the west coast had made our air toxic, so I'd been indoors for the past four days. We'd already been at home all day because of the pandemic, but at least we could go for hikes and bike rides and walks. Now we just had the surrounding walls of our home.
SmartBear recently published its 2020 The State of API report, which collected responses to 52 questions from 3,500+ respondents. Reading this report will make any technical writer feel like he or she has an important role with API docs. However, the report also notes that 'API documentation represents big opportunity for improvement,' which I think suggests that many existing processes for documentation in the software are kind of broken.
So many documentation websites rely on search as part of their information architecture. But what do you actually need to consider if you want to make your site search return answers for users in relevant, efficient ways? Join Peter Levan from Funnelback with regular guests Chris, Jared, and Tom for a talk all about making search work well on your site. Some of the questions discussed include: Why can't you just let Google do the searching and indexing for you? Do you need to pay big money to get a site search tool? How do you make your docs site talk robot?
I added a lengthy tutorial in the API doc course for using Redocly. Redocly provides a variety of tools for working with API docs. Using Redocly's command-line tools, you can split the OpenAPI definition into many sub-files, and then later bundle up the discrete files into a single file during the publishing stage. You can generate your docs into one of the most attractive outputs available for REST API docs, including integration with conceptual topics as well. Redocly also offers more robust developer portals and SaaS offerings that cover the full authoring and publishing lifecycle.
At some point after receiving a new documentation project, the first step in the project is to hold a documentation kickoff meeting and product demo. These meetings are mostly about gathering information so you can create the documentation. The following are some initial questions and topics for these meetings.
If you need an inexpensive way to host media, and your egress GB bandwidth (related to site traffic) is less than the GB data you're storing, Wasabi might be an option to explore. Combined with GitHub Pages, this could be an inexpensive way to host a website.
I recently wrote an article for the Institute of Scientific Technical Communicators (ISTC) magazine Communicator called 'Developer documentation trends: How developer documentation trends differ from general technical communication trends.' This article provides the official writeup and analysis from the developer documentation survey that I conducted at the beginning of the year.
In this podcast, I chat with Jonathon Colman about an innovative work model they implemented at Intercom with content designers. In their experimental model, content designers were allocated to one project only, and they expanded their roles to include not only content design but product design as well. These content/product designers engaged on a deeper level to help products succeed.
A recent episode of Command Line Heroes explores the negatives of toxic 10X coders. I think a change in mindset to acknowledge how each of us climbed to our levels can help avoid some of the toxicity inherent in 10X.
I added a new article covering SDK release processes in my API course. Even if engineering teams distribute the SDKs, they often look to tech writers for guidance on the Readme, signoff, and other input. The process in the article describes a few callouts that you should look for before distributing SDKs and other code artifacts. You can read the article here: Processes for managing SDK releases.
I added an article about content strategy for the developer experience to my API doc course. As the content grows on a developer portal, there's an increasing need for some technical writers to expand their documentation roles from individual contributors creating and publishing new content to dedicated content strategists instead. These dedicated content strategists manage the processes, standards, tools, governance, and workflows for the content that is primarily authored by contributing teams. You can read the article here: DX content strategy with developer portals.
