New article in API doc course: Using Oxygen XML in docs-as-code workflows
I added a new article in my API doc course about how to use Oxygen XML in a docs-as-code workflow. Oxygen XML is a robust authoring and publishing tool for technical content that allows you to author in multiple formats (Markdown, HTML, or XML) as well as publish to multiple outputs (HTML-based webhelp, PDF, and more). Although traditionally used for XML authoring and publishing, Oxygen XML has expanded its support with Markdown files, especially with the DITA's recent support for Lightweight Markdown. In this new article, you'll learn more about Oxygen XML, different workflows you can use to publish in a docs-as-code model, Git integration with Oxygen XML, supported Markdown formats, how to get started, and more. (Note that this is a sponsored post.) Read more here: Using Oxygen XML with docs-as-code workflows.
Biking and public transportation in Renton and Seattle: Solving the first-mile and last-mile problems
Last month I wrote a post about returning to normal, and as part of that return, I wanted to commute to work. Part of why I like the commute is because for the past decade, I'd been biking to work. That biking window provided me with a built-in time for daily exercise, and I also liked the space to wind up and wind down for the day. When I lived in California, I was fortunate enough to live next to a paved trail (following a canal) that took me 75% of the way to work; the remaining 25% was along a road with a bike shoulder, and only 5% on a treacherous road (which has since been fixed for cyclists). But biking to work from Renton to Seattle is a different problem to solve. In this post, I'll talk about strategies for the first mile (getting to the transit hub) and the last mile (getting from the transit endpoint to your actual destination). Even though this post will have specifics about my area, the same struggle likely exists for anyone trying to bike to work in any city.
Upcoming webinar -- 'Best practices in API docs: Product overviews and getting started tutorials'
I'm giving an online webinar, sponsored by the STC Washington, D.C.-Baltimore Chapter, on October 28 about product overviews and getting started tutorials in API docs. This post provides details about the webinar and a link to sign up.
tcworld China 2021 keynote: 'Tech comm and marketing: How to make your tech comm group more visible to those within your company'
I recently gave a keynote presentation at tcworld China 2021 on the topic of tech comm and marketing. This post provides a recording of the presentation, slides, and detailed notes for the presentation.
New article in API doc course: 'Ensuring documentation coverage with each software release'
I added a new article in my API doc course called Ensuring documentation coverage with each software release. Getting a good handle on your release process -- such as understanding the cadence of releases, how features are tracked and tagged in different phases, and other checkpoints prior to the release signoff -- is central to thriving in any documentation role. Providing doc coverage for each release ensures you don't accrue documentation debt, and it boosts user satisfaction for the new features being released. This article adds to about a dozen other process-oriented articles in the processes and methodology section.
Sending doc status reports -- a tool for visibility and relationship building [API doc course]
I recently added an article titled Processes for reporting status to business stakeholders to my API course. Sending documentation status reports can help foster trust and awareness with your business stakeholders. These stakeholders might be the core leadership within your organization or simply your management chain the next level up. Besides building visibility and relationships with these stakeholders, creating these status reports each month gives you a regular cadence for doc assessment and analysis, which is also helpful.
Recording of 'Product overviews vs. getting started tutorials: striking a balance between read-first and try-first user behaviors'
I recently gave a webinar to tekom Europe about product overviews and getting started tutorials. The recording and slides are below.
Review of "Hashtag #TechComm: An Overview of Members, Networks, and Themes from 2016-2019"
In Hashtag #TechComm: An Overview of Members, Networks, and Themes from 2016-2019, published in Technical Communication Journal (68.2 May 2021), Chris Lam identifies trends and themes in the tech comm field by looking 75,000+ tweets that used the hashtag #techcomm from 2016 to 2019. Previously, academics looked at job advertisements to identify trends, so this Twitter analysis for data provides a new approach to identifying trends.
New sections in API doc course exploring causes for poor product overviews and getting started tutorials
I added two new sections in my API doc course exploring reasons for poor product overviews and sometimes absent getting started tutorials. I'm still adding to this section but wanted to share the current content. These are all first drafts that I hope to refine a bit with more imagery, proofreading, examples, and other detail, so if you have feedback, let me know in the comments. I'm trying to explore reasons why these two content types often fail or are weak. It's less of a best practices section and more like an analysis about causes.
Five basketball strategies and how they might apply to tech comm
Because it's NBA championship finals time, I thought it might be fun to write a basketball-themed post focusing on basketball strategies that succeeded or failed, and how any of these strategies might apply to technical writing. Beyond the specifics of any particular strategy, the larger application to tech comm is to simply formulate a strategy, to think strategically about how to "win" at technical writing. With that, let's jump into five basketball strategies.
Balancing product overviews with getting started tutorials
In my experience writing documentation, at least two topics seem to be frequently neglected: product overviews and getting started tutorials. Not all the time — many companies also have great product overviews and excellent getting started tutorials. But I often have the misfortune of arriving at documentation portals and feeling lost, and I don't find much help in the product overview. If there's a getting started tutorial (not usually), my success rate for getting through it is low.
Write the Docs Podcast Episode 34: Adding personality to documentation, with Fabrizio Ferri
In this podcast, Fabrizio Ferri joins us for a discussion about adding both personal identity and personality to documentation. Why are the docs we write so often anonymous, and does that anonymity work against career progression? Are tech writers, typically introverts, averse to publicity, or does our industry not allow for it? And if you want to be a "personality" in the tech communications world, what do you do? How do you add personality constructively to your work without disrupting corporate brand and consistency?
Five project management responsibilities of senior technical writers
Last week I wrote a post about ambiguous content and how one aspect of being a senior tech writer is taking on more ambiguous projects. In this post, I want to continue this thread on what it means to be a senior tech writer, or even a lead technical writer. But rather than exploring ambiguous content, senior/lead tech writers also have a lot more project/program management responsibilities as well. There are at least five key responsibilities I'll explore here: prioritizing work, defining doc strategies, organizing work among multiple writers, reviewing contributions, and reporting upward.
Trying to get back to normal
As the pandemic winds down in the US, I've been trying to get back to normal. I've been especially motivated to find this normal because I made both a job transition and a home relocation during the pandemic, so I don't have the context of what normal even looks and feels like. I can't "return to my workplace" because I'd never seen my new workplace. I don't dread the commute because I'd never made the commute (from my new home). Since moving to Renton, which is 30 minutes below Seattle, my experience has mostly been within the walls of our home and the green woods here. So for the past couple of weeks, I've set about experimenting with several ways to return to normal. In doing so, I've been surprised by how much I've forgotten.
Paligo: Structured Authoring and Component Content Management made easy
Paligo is an online XML-based CCMS for authoring teams that are either looking to level up from help authoring tools to robust structured authoring and component content management, or for teams that want to escape the complexity and cost of their legacy CCMS. Paligo simplifies structured authoring with a visual interface that teams can access through an online portal. In this post, I explain Paligo's context within the CCMS landscape, how it's different from HAT tools, and why it's a documentation solution worth considering for both enterprises and small businesses.