I'd Rather Be Writing Podcast Feed

I recently gave a presentation to the STC San Francisco chapter called "Beyond mere endpoint reference — the overlooked content in API documentation" on February 21, 2018. You can browse the slides and listen to the audio recording here.

Video You can watch two versions of the video. If you want the STC San Diego version that includes my talking head and the STC / WTD intro remarks, see this video: I didn’t like how my talking head seemed to squish the video over to the left, so I also uploaded my own recording. This second recording excludes the talking head and expands the window full screen, and also shows the chat window and occasional webinar controls. Slides Here are the slides: Audio only Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Presentation description Swagger UI and the OpenAPI specification OpenAPI is a specification for describing REST APIs. As an analogy, you can think of the OpenAPI specification like the specification for DITA. With DITA, there are specific XML elements used to define help components, and a required order and hierarchy to those elements. Different tools can read DITA and build out a documentation website from the information. With OpenAPI, instead of XML, you have set of JSON objects, with a specific schema that defines their naming, order, and contents. This JSON file describes each part of your REST API (the endpoints, parameters, responses, etc). By describing your API in a standard format, publishing tools can programmatically ingest the information and process it. Swagger UI provides one option to read the OpenAPI specification document and generate an interactive documentation website from it. Interactive documentation created with Swagger lets users try out requests and see actual responses directly from within the documentation. You can read the details in either the STC or WTD event pages: STC San Diego Write the Docs - San Diego The event was held February 13, 2018. var contents=new Array() contents[0]=' Sponsored message:Over 40,000 API developers use SwaggerHub to design and document APIs with Swagger (OpenAPI). Learn how SwaggerHub can help improve your team’s API documentation workflow. Get started for free.' contents[1]=' Sponsored message:SwaggerHub was built by the team behind Swagger to help organizations collaborate on their API design and documentation from one centralized platform. Find out why SwaggerHub is the platform for design and documenting APIs with Swagger. Get started for free.' contents[2]=' Sponsored message:SwaggerHub brings together all the power of the open source Swagger tooling into one integrated platform for designing and documenting APIs with Swagger (OpenAPI). Get started for free.' contents[3]=' Sponsored message:SwaggerHub is an integrated API design and documentation platform, built for teams to drive consistency and discipline across the API development workflow. Get started for free.' contents[4]=' Sponsored message:Documenting APIs with Swagger? SwaggerHub lets you generate API documentation that’s securely hosted and fully interactive. Import an existing Swagger definition, or start a new API project from right within your browser, no setup required. Get started for free.' var i=0 //variable used to contain controlled random number var random //while all of array elements haven't been cycled thru while (i

I recently gave a presentation to the STC San Diego chapter and WTD San Diego group called "Swagger UI and the OpenAPI specification" (February 13, 2018). You can view a recording of the presentation, browse the slides, and listen to the audio here.

Slides Here are the slides: Audio Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Video Event Description The description is as follows: Publishing tools for API documentation In developer documentation spaces, technical writers often employ more developer-centric tools to author and publish documentation. These developer-centric tools usually involve treating documentation like code – this means managing the content with git workflows, using open-source tooling such as static site generators, formatting the content in Markdown, building from the server, and so on. Additionally, when documenting REST APIs, many documentarians use standards such as the OpenAPI specification to describe the API. Various tools, such as Swagger UI, can read the OpenAPI specification and generate interactive documentation that lets users try out the endpoints directly in the browser. Integrating Swagger UI’s output with the rest of the documentation can be challenging, but many doc sites do it seamlessly. In this presentation, we’ll explore this landscape of authoring and publishing tooling in the API documentation space. Some questions we’ll explore involve the following: Why do API documentation projects often abandon traditional help authoring tools? What unique needs do API technical writers have? What are some pros and cons of the docs-as-code approach? What are some common tools and workflows used by API documentation groups? What challenges are inherent in these docs-as-code tools, particularly with search, localization, and validation? What approaches are writers taking to merge structured authoring techniques with the more open, unstructured docs-as-code techniques? For details, see the event description on the WTD San Francisco meetup group: Publishing tools for API documentation. Location and other details The meetup was held at the Google campus in Mountain View. Details are on the meetup event details. Date: Jan 18, 2018 Time: 6:30-8:30pm Location: Google Building 1310, 1310 Shorebird Way, Mountain View, CA Cost: Free but you must RSVP through meetup.com. This was the first “South Bay” meeting for the WTD San Francisco group. South Bay includes pretty much everywhere from Redwood City down to Morgan Hill. var contents=new Array() contents[0]=' Sponsored message:Over 40,000 API developers use SwaggerHub to design and document APIs with Swagger (OpenAPI). Learn how SwaggerHub can help improve your team’s API documentation workflow. Get started for free.' contents[1]=' Sponsored message:SwaggerHub was built by the team behind Swagger to help organizations collaborate on their API design and documentation from one centralized platform. Find out why SwaggerHub is the platform for design and documenting APIs with Swagger. Get started for free.' contents[2]=' Sponsored message:SwaggerHub brings together all the power of the open source Swagger tooling into one integrated platform for designing and documenting APIs with Swagger (OpenAPI). Get started for free.' contents[3]=' Sponsored message:SwaggerHub is an integrated API design and documentation platform, built for teams to drive consistency and discipline across the API development workflow. Get started for free.' contents[4]=' Sponsored message:Documenting APIs with Swagger? SwaggerHub lets you generate API documentation that’s securely hosted and fully interactive. Import an existing Swagger definition, or start a new API project from right within your browser, no setup required. Get started for free.' var i=0 //variable used to contain controlled random number var random //while all of array elements haven't been cycled thru while (i Other API doc presentations I’m giving a few API doc presentations this year. They won’t all be the same presentation. Instead, I’m covering different sections in my API documentation course. Whereas the STC Silicon Valley presentation covered the Intro to API documentation section, Using a REST API like a d

I recently gave a presentation called "Publishing tools for API documentation" to the Write the Docs South Bay meetup group on January 18, 2018. You can view a recording of the presentation, browse the slides, and listen to the audio here.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Since my last post on balancing writing, editing, and learning, I’ve been trying to read more. The problem is, despite the tradition of writers being “voracious” readers, I’m not one. I should revel in reading, staying up late at night to immerse myself in books, but I don’t. Why? Of course, I do read, both fiction and non-fiction. I often listen to fiction while I bike to work. My fiction tastes are low-brow, mostly consisting of the larger-than-life spy/CIA/military genre fiction (with protagonists like Jack Reacher, Mitch Rapp, Dewey Andreas, Evan Smoak, etc.). I listen to fiction as an escape, to be immersed in story while biking with partial attention. However, when I sit down to read, I’m fully alert mentally, so I am eager to be more intellectually engaged. As such, I read non-fiction. Ideally, I like to read an author who asks the same questions I’m interested in. I want to see a mind thinking, but I don’t want a stream of conscious or text full of tangents. I want the narrator to take me down the mental path he or she is exploring. In short, I want to read a modern-day Montaigne, someone essaying forth and chasing ideas and working through answers. It’s hard to find authors who write like that. When I was in college, I read a lot of literary essays and fell in love with the personal essay style that authors like Joseph Epstein, David Foster Wallace, and Phillip Lopate mastered. But now, when I read literary nonfiction, I’m usually bored by the slow setup, the over-abundance of personal details, the arduous painting of a mostly uninteresting scene and eventual story. The ideas tend to be unexciting, contain too much memoir, and I find myself quickly looking for another genre. The books that appealed to me in college don’t appeal to me today. I’m now a working professional and family provider, and I’m more cautious about the demands on my time. I have little patience for topics that don’t seem relevant. It could take hours or weeks to sit down and read a book from cover to cover. I assess the ROI of any endeavor. Will it give me new awareness or skills, or at least satiate a deep curiosity about something? If not, I might not have the time. Now more than the author’s style, I choose books by relevant topics. As a technical writer, tech-comm-related books are relevant, but they’re typically either beginner or reference. Both put me to sleep. Philosophy appeals to me, but the higher-level, abstract questions they ask (what exists? how can we know it? is there free will?) don’t always resonate with me. At the end of the day, the topic probably doesn’t matter much. All topics, if examined deeply enough, reach down into the same roots. It’s the analytical mind that’s interesting, regardless of the content. So why am I not reading more? Reading for reading’s sake can be a chore, especially if it’s the wrong text. My problem is that I sometimes read without purpose. I need to more firmly ground my reading by searching for answers to my own questions. Answering questions is at the heart of both writing and reading. In most non-fiction texts, an author begins with a question. Some authors make the question explicit, while others begin with the answer directly. Identifying the question the author is trying to answer is the first step toward engaging with texts. Once the question is identified, the reader decides if it’s relevant. If so, the reader figuratively gets in the passenger seat while the author drives toward the answer. A skilled author takes you on the journey to find the answer, showing you the roads traveled, the detours, the vistas, and other scenery along the way. You don’t want the author to drive aimlessly or circuitously, but you also don’t expect a straight shot. In the end, difficult questions rarely have clear-cut answers, so the author usually finds some partial answer that yields some satisfaction. If it’s the

Voracious reading begins with voracious thinking. Asking questions gives us a purpose and drive for reading.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Differences in the idea of “learning” between tech comm and eLearning One difference between tech comm and eLearning is how each discipline approaches the idea of “learning.” Tech comm focuses more on learning just when the user needs the information. Tech writers produce documentation so that users can quickly find an answer and use it to solve a problem. The whole interaction — user needs info, consults docs, finds answer, returns to work context — takes place fairly quickly. Some people call this “just-in-time learning” or “informal learning.” eLearning approaches learning as more of a long-form course or training that a user undergoes to ramp up their knowledge and skills from one level to the next. It’s not a quick interaction but rather might take an hour or to several weeks, depending on the material. eLearning developers define learning objectives that they use to build a course around, and then sequentially take users module by module through the learning objectives. Along the way, to ensure progress toward the objectives, eLearning developers incorporate exercises, quizzes, and other interactions to ensure engagement and learning. Reference content versus a “course” When I created my API documentation site, I compiled the material as reference content for workshops I was leading. I didn’t approach the content as an eLearning deliverable, because eLearning concerns aren’t in my tech comm DNA. However, after I started receiving a lot of feedback from users who were progressing through the material as a “course,” I started to consider some of these eLearning considerations. Users aren’t consulting my API documentation material as a just-in-time learning situation, where they go to quickly consult the right terminology for documenting an endpoint and then return to their work context. Instead, most users want to transition into the field of API documentation. Either they’re traditional tech writers working with software documentation and want to make the switch, or they’re students trying to ramp up their skills for a future job. Others are tech writers who are assigned an API doc project at work and need a course of some kind to learn the needed skills. In short, I now suddenly find myself in an eLearning situation. I’m developing a “course” when course development isn’t usually in my target sights. I’m a technical writer. I produce information, not long-form learning experiences. How do I pull users from start to finish through a whole course and help them achieve their larger career objective? How can I inspire and motivate my users to consume and complete long-form material? In The Progress Principle: Using Small Wins to Ignite Joy, Engagement, and Creativity at Work, researchers Teresa Amabile and Steven Kramer argue that the greatest motivation comes from feeling a sense of progress. They explain: Real progress triggers positive emotions like satisfaction, gladness, even joy. It leads to a sense of accomplishment and self-worth as well as positive views of the work and, sometimes, the organization. Such thoughts and perceptions (along with those positive emotions) feed the motivation, the deep engagement, that is crucial for ongoing blockbuster performance. They base their research in work scenarios with managers and employees, looking through “nearly 12,000 diary entries provided by 238 employees in 7 companies” (rather than examining eLearning scenarios) to arrive at their conclusions. But I think the conclusions apply to both scenarios. The idea of progress resonates with me. When I sense that I’m actually making headway on a goal, it fills me with motivation. Amabile and Kramer talk about progress as a “principle” to leverage, arguing that — of all the positive events that influence inner work life, the single most powerful is progress in meaningful work; of all the negative events, the single most powerful is the

When you don't have a system that logs users in and tracks their progress, it can be a challenge to show their progress in a course. However, rather than showing progress through completed pages, quizzes, or other interactive exercises, progress can also be measured through larger user goals that extend beyond the course. In the case of my API documentation course, the user's goal is to break into the field of API documentation, not so much to finish a course. Breaking into API documentation requires users to build a compelling portfolio, which is how I'm choosing to measure the user's progress.

Video Audio Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Slides My slides are here: idratherbewriting.com/intro-to-api-documentation. Presentation details To view more details about the API doc presentation, see the STC Silicon Valley event details: November 20, 2017: Introduction to API Documentation. Here’s the presentation description: Introduction to API Documentation In Silicon Valley, there’s no greater demand for tech writers than with API documentation roles. This is primarily because, unlike traditional documentation around user interfaces, APIs are primarily marketed through their documentation. As such, the API documentation has a huge impact on the success and adoption of the API. At its core, REST API documentation focuses on requests and responses. You describe the various endpoints available, their methods, parameters, and other details, and you also document sample responses from the endpoints. To test the endpoints, you often make sample requests using tools such as cURL and Postman. In this presentation, you’ll learn what a REST API is, the 8 essential sections in endpoint reference documentation, and how to test and analyze API requests. You can find more details in my API documentation course here. Note that this presentation is geared towards beginners, not advanced gurus who have worked on API doc projects for a number of years. Also, I don’t cover any new material that isn’t already in my API documentation course. Specifically, I briefly cover these first 3 sections from my API doc course: Introduction to REST APIs Using a REST API as a developer Documenting endpoints To learn more about the Silicon Valley chapter of the STC, see http://www.stc-siliconvalley.org. var contents=new Array() contents[0]=' Sponsored message:Over 40,000 API developers use SwaggerHub to design and document APIs with Swagger (OpenAPI). Learn how SwaggerHub can help improve your team’s API documentation workflow. Get started for free.' contents[1]=' Sponsored message:SwaggerHub was built by the team behind Swagger to help organizations collaborate on their API design and documentation from one centralized platform. Find out why SwaggerHub is the platform for design and documenting APIs with Swagger. Get started for free.' contents[2]=' Sponsored message:SwaggerHub brings together all the power of the open source Swagger tooling into one integrated platform for designing and documenting APIs with Swagger (OpenAPI). Get started for free.' contents[3]=' Sponsored message:SwaggerHub is an integrated API design and documentation platform, built for teams to drive consistency and discipline across the API development workflow. Get started for free.' contents[4]=' Sponsored message:Documenting APIs with Swagger? SwaggerHub lets you generate API documentation that’s securely hosted and fully interactive. Import an existing Swagger definition, or start a new API project from right within your browser, no setup required. Get started for free.' var i=0 //variable used to contain controlled random number var random //while all of array elements haven't been cycled thru while (i

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.

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...

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. A world standard for describing REST APIs Smartbear recently announced support for new OpenAPI 3.0 version of the spec in SwaggerHub. The 3.0 version of the OpenAPI spec provides a number of enhancements, such as providing support for callbacks, linking between operations, more robust properties with examples, and easier content re-use. You can read about OpenAPI’s 3.0 features here. (Note: Before continuing, I want to clarify a few terms for those who may be unfamiliar with the OpenAPI/Swagger landscape. “Smartbear” is the company that maintains and develops the open source Swagger tooling (Swagger Editor, Swagger UI, Swagger Codegen, and others). Smartbear formed the “OpenAPI Initiative” and leads the evolution of the “OpenAPI specification”. “SwaggerHub” was developed by Smartbear as a way for teams to collaborate around the OpenAPI specification file. “Swagger” was the original name of the spec, but it was changed to “OpenAPI” to reinforce the open, non-proprietary nature of the standard. People often refer to both names interchangeably, but “OpenAPI” is the preferred term. The Swagger YAML file that you create to describe your API is called either the “OpenAPI specification file” or the “OpenAPI contract.” Now that I’ve cleared up those terms, let’s continue.) I’ve written in the past about how Swagger-related posts are the most visited posts on my site. The OpenAPI/Swagger specification (instead of RAML or API Blueprint) continues to be the most dominant specification for describing REST APIs. In a recent webinar description about the OpenAPI 3.0 spec, Smartbear says OpenAPI “has emerged as the world’s standard for defining and describing RESTful APIs” — it would be hard to argue otherwise. Because of this emergence as the world standard, in my API course, I added a tutorial on OpenAPI/Swagger and another tutorial on Managing OpenAPI/Swagger Projects with SwaggerHub. Note: SwaggerHub is one of the sponsors of my site. Why OpenAPI is so popular What accounts for OpenAPI’s popularity and wide acceptance? I think the OpenAPI spec continues to be popular because it provides a standard in an area of technology that is a wild west of differing options, approaches, and terminology. Many technical writers who want to learn more about API documentation are overwhelmed by the breadth and diversity in this space. The challenge is not so much that there are new terms, new tools, and new documentation techniques to learn. The challenge is that there are so many conflicting terms, competing tools, and varying documentation techniques that unless you’re a maven with APIs, it’s hard to know the right path to follow. For example, what do you call all of your endpoints/methods/objects/resources/paths? How do you refer to the various types of path/query/body/head parameters? What template or pattern or arrangement do you follow in your API documentation to cover the various elements in the API reference as opposed to other non-reference API topics? Do you auto-generate the spec file from the code, or do you create the spec file manually? Do developers write the content, or do technical writers, or both? Where do you publish your API docs, and how do you integrate the information into your user guides and other help material? Documenting an API is like being dropped off in a busy, bustling city in another continent, without a map or idea of transportation, and without a clear idea of where you even need to go, just that you need to go somewhere, and do something. It can be overwhelming, because not only is the approach you should take in your documentation unclear, the developer-based nature of the content is often complex as well. When you discover the OpenAPI specification for describing REST APIs, you suddenly have a map and a direction. You have a language to describe it all. You have a documentation template to populate. You have an idea

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.

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.