Intro to API Documentation -- recording of presentation to STC Silicon Valley chapter on 11/20/2017
I recently gave a presentation titled "Introduction to API Documentation" to the STC Silicon Valley chapter in Santa Clara, California. The video recording and audio are available here.
Balancing writing, editing, and learning in equal measures
Writing is an activity that is best balanced with equal measures of editing and learning. Overdoing any one activity can lead to exhaustion and burnout, but by balancing these three activities — writing, editing, and learning — you can switch to different neural muscles and find more energy in the long-term.
New OpenAPI 3.0 specification tutorial in my API Course
I added a new tutorial on creating an OpenAPI 3.0 specification document in my API course. (OpenAPI was formerly referred to as Swagger.) The tutorial has 8 steps and guides you through the process of creating the specification document in the context of a sample weather API. Additionally, I explain how the specification fields get displayed in Swagger UI. Swagger UI is the display framework that reads the OpenAPI spec and generates an interactive documentation website.
The Untold Story of Techwriter.pl: A Polish website about technical communication for technical writers, trainers, and translators
Techwriter.pl is an online hub of information for technical writers in Poland. Although it's maintained by volunteers, the site continues to thrive from its inception in 2013 up through today. The following is a guest post by Michal Skowron and Jakub Wisniewski, two Poland-based technical writers who helped shape Techwriter.pl and who wanted to tell the story of the site.
Question: Which software tools should I use if my goal is to write API docs?
Finding the right software tools to write API docs is a constant and difficult challenge given the wide variety of tooling and environments in the developer doc space. However, if your goal is to break into developer documentation (rather than specifically reworking your company's documentation tools), you would be better off deepening your technical background with programming languages rather than focusing on doc tools.
Write the Docs Podcast episode 10: What's going on in our lives as documentarians and product owners
In this episode of the Write the Docs podcast, we talk about what's going on in our lives as documentarians and product owners. We don't have special guests during this episode. Instead, we discuss challenges we're facing and any interesting aspects of our documentation lives.
SwaggerHub: A collaborative platform for working on OpenAPI/Swagger specification files, and more
When documenting REST APIs, the OpenAPI specification (formerly called Swagger) is pretty much the default standard. Yet learning the OpenAPI spec is not a trivial undertaking and requires significant ramp-up. SwaggerHub is a tool can reduce the complexity in creating your OpenAPI spec file because it enables collaboration between both developers and technical writers. This collaboration not only helps compensate for gaps in understanding with the spec, SwaggerHub also offers many other features (such as versioning, content re-use, inline commenting, and more) to make the authoring and publishing experience easier.
Convert Google Docs content to Markdown or HTML using the gd2md-html add-on
gd2md-html is a Google Docs add-on that will convert your Google Doc content into either Markdown or HTML. This tool provides a much-needed converter that enables you to use Google Docs as a platform for content development without manually reformatting the content when you're ready to publish it in another system.
Has plain language deepened or ruined our delight in language?
Although technical writers champion plain language, embracing plain language for many years can cripple your ability to use more eloquent language, like that of a literary author or essayist. There isn't much room for literary play or playful tones in technical documentation. Following the rules of simple language has distorted my ability to read anything that blatantly violates those rules without questioning the author's word choice and sentence construction. Sometimes I feel that simple language has removed my ability to delight more in language and to express myself in more articulate, interesting ways.
Write the Docs Podcast episode 9: Chatbots in Documentation
In this episode of the Write the Docs podcast, we're joined by Ellis Pratt from Cherryleaf to talk about chatbots in documentation. What are chatbots, and how can you incorporate them in your docs to enhance the user experience? Are chatbots the next evolution of wizards? What are some examples of successful chatbots? How does one get started using chatbots in documentation? Are there chatbot services you can leverage inexpensively to try them out? These are some of the questions explored in this podcast.
Discoveries and realizations while walking down the Docs-as-Code path
This past week I had some good discussions with developers about the right directions in our doc-as-code project at work. I say good discussions, but actually they were challenging. The outcome led me to realize more details about embracing docs as code. The more you treat docs as code, the more you may have to set aside some common tech writer models of handling content and instead embrace the software code workflows entirely. Some of these principles include storing only source code in repositories, building from a build management system, and reducing build pipelines to work with 1 or 2 larger repositories only.
Write the Docs Podcast episode 8: Stack Overflow's Documentation Failure and Open Source Challenges
In this Write the Docs Podcast episode, we're joined by Beth Aitman to talk about what happened with the Stack Overflow Documentation Beta. What did Stack Overflow try to do with documentation, and why did they abandon the effort? Why did their effort to crowdsource docs fail but succeed so well with forums and niche content? Additionally, we discuss the difficulties of creating good documentation with open source projects. A recent survey found that incomplete or outdated documentation is the number one issue with open source projects. Why? What makes it so difficult to create documentation on an open source project?
Why Stack Overflow's Documentation effort failed -- a few thoughts from a technical writer's perspective
Stack Overflow, mostly known as a forum for answering niche software questions, recently tried to launch a Documentation component to their site. The goal of Documentation was to 'do for Documentation what we did for Q&A'. In other words, provide substantial, valuable information that could be the go-to source for tech docs instead of just one-off answers around niche topics. However, the effort failed and now Stack Overflow is sunsetting their Documentation.
Tech docs and Agile: Alternatives to integrating into engineering Scrums (Part 2)
This is part two in a series on Agile and tech docs. In the previous post, I outlined challenges in integrating into engineering Scrum teams. Some alternatives to Scrum include Kanban, Extreme programming, Waterfall, and various productivity methodologies. The most compelling solution, to me, seems to be to form your own documentation-focused Scrum. This allows you to keep with the same project management approach and language in the company, while also allowing you to avoid the pitfalls previously described with integrating into an engineering Scrum. Even so, there's not an extremely compelling reason for docs to adopt Scrum, so its main aid might be to give you a disciplined approach to your doc work.
Tech docs and Agile: Problems with integrating tech writers into engineering Scrums (Part 1)
Although it seems like documentation should be treated like other features worked on by a Scrum team, frequently it is not. When tech writers try to integrate into engineering Scrum teams, they usually run into a host of challenges. These challenges stem mainly from floating across multiple projects. Often doc tasks aren't assigned points or grouped in with other tasks in a real sprint, nor are tech writers co-located with project teams. This is a two-part post. In this first part, I outline problems for tech writers integrating into Scrum teams. In part 2, I explore solutions.