Expanding embedded Swagger UI instances in your docs
One challenge with REST API docs, if you're generating out the reference content using Open API, is how to embed Swagger UI in your docs in a seamless way that doesn't look like a website within a website. In this post, I explain how to embed a Navigation toggle to hide your sidebar and give more width to the embedded Swagger UI display.
Write the Docs Podcast episode 24: Conference chatter and the Australian scene, with Swapnil Ogaler
In this episode, Chris and Jared are joined by the Write the Docs Australia initiator Swapnil Ogale. They talk about conference wind-downs and ramp-ups, highlights from the just-finished WTD Prague conference, speakers announced for upcoming Write the Docs Australia conference, the "Good Docs Project," the tech writing scene in Australia, and more.
Write the Docs Podcast episode 23: How to write inclusive tech documentation, by Lucie Le Naour
In this episode of the Write the Docs podcast, rather than the usual roundtable discussion, we provide a recording of a WTD Berlin presentation by Lucie Le Naour on how to write inclusive tech documentation. Inclusive documentation takes into account all users, regardless of their gender, culture, or abilities. It uses language that treats different types of people fairly and equally, acknowledging that the words you choose matter in the connotations and attitudes they convey. This presentation was recorded on August 19, 2019 in Berlin.
An inside look at DeveloperHub -- hosted documentation portals for API docs
DeveloperHub is a new publishing platform for API documentation that lets you combine your API reference information with tutorials and other documentation, complete with search, branding, navigation, and other features in a developer portal. In this post, I asked Zaid Daba'een, CEO & Founder of DeveloperHub, to share a bit of info about DeveloperHub.
Upcoming API Documentation Workshop in San Francisco, Calif., on November 19, 2019
What I learned from organizing and running my first API documentation workshop from end to end
This past week I held my first API documentation workshop in which I organized it from start to finish myself (handling registration, venue, dates, catering, marketing, setup, and other details), and now I'd like to reflect a bit on it.
New topic in API course: Following agile scrum with documentation projects
I added a new article in my API doc course that expands the notion of docs as code to include not only tools but processes as well. I included an excerpt below and a link to the full article.
Can you collaborate on doc projects in Git with other writers?
A reader recently asked how to collaborate with Git with other writers. He said they found it hard to develop a Git workflow that allowed them to work on content together and wondered if another approach might be more suitable.
New topic in API course: Five strategies for documenting code
Previous articles I've shared on documenting code introduced the complexity of the challenge. In this article, I expand on five different techniques writers take in documenting their code, including the Lego approach, the Nautilus approach, juxtaposed columns, and more. In particular, I expand on why describing the finalized code might not be so instructive for users, and why it's nearly impossible for writers to decompile the developer's logic that led to the finalized code anyway. See Five strategies for documenting code.
New topic in API course: Research on documenting code
I added another topic to the Documenting Code section in my API documentation course. This new topic is called Research on documenting code and summarizes/discusses two academic articles on documenting code.
New topic in API course: Why documenting code is so difficult
I recently added a new section in my API documentation course on documenting code. This is an entire section that I'm building out with about 7-8 topics. The introduction is called Why documenting code is so difficult.
Write the Docs Podcast episode 22: Managing multiple doc projects across Git repositories, with Giles Gaskell
In episode 22 of the Write the Docs podcast, Giles Gaskell from Squiz in Australia joins us to talk about managing multiple doc projects across Git repositories through Antora. Giles explains how to establish processes such that updating documentation becomes part of the definition of done, how to manage build process across multiple Gitlab repositories, strategies for distributing doc work across engineers through templates, how to scale workloads when you're the lone technical writer in the company, times when dogfooding your own product for docs makes sense and when it does not, pros and cons of Asciidoc versus Markdown, and more docs-as-code topics.
Single-sourcing data into table templates in Jekyll
Jekyll lets you separate out your data from your presentation layer. You can store your data in a YAML file and then populate the data into templates as desired, passing parameters into includes. In this post, I describe my process for creating tables where I might re-use the same definitions in various places in the docs.
Upcoming API Documentation Workshop in Mountain View, Calif., on August 30, 2019
I'm giving an API Documentation Workshop in Mountain View, California, on August 30, 2019. Although I've given more than a dozen API documentation workshops at various conferences over the past several years, this one is different. For this workshop, I'm organizing it myself. You can register on Eventbrite.
Every project is a monster you battle and slay
Some tech comm projects are like monsters we battle. Is there any truth to the idea that it takes a monster to kill a monster?