I'd Rather Be Writing Podcast Feed

Listen to the podcast You can download the MP3 file here. Summary Bob was a software engineer for 17+ years. He decided to get a PhD from the University of Washington’s Human Centered Design and Engineering because he felt that if the documentation for his software were better, the adoption of the software would increase. This led him to pursue research in technical communications. He soon found that many other factors besides documentation contribute to product adoption. Still, the tech comm domain held his interest, as it contained many interesting problems to solve. For his PhD, Bob examined several questions related to API documentation: How does the design of API reference documentation affect the user experience? How does the relevance of the content on API reference documentation affect the user experience? How does the length of the content on API reference documentation pages affect the user experience? He found that his changes to the topics’ visual design didn’t affect performance — whether your API documentation has lots of design elements or not didn’t affect how quickly people found the information to achieve a goal. A strong visual design did, however, affect people’s perception of the documentation’s credibility and professionalism. He also found that whether reference topics contained relevant information or not, people spent the same amount of time evaluating the topic for relevance (about 44 seconds). Finally, he found that topic length influenced performance. Shorter topics were quicker to assess, but longer topics increased the user’s perception of the topic’s credibility and professionalism. 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 Goal testing documentation We also talked about testing. Bob said his background as a software engineer, a context in which code is heavily tested, led him to wonder why documentation wasn’t also tested with the same degree of thoroughness. He found that testing documentation content was much more difficult. It’s harder to determine whether documentation is achieving its goal, especially with API reference documentation, since a user may not implement the knowledge gained from the content until later, such as when the user writes code for an application he or she is building. Bob noted several practical approaches to testing. One method is to get a new engineer in your company to test your documentation. He recommends designing 10- to 30-minute tests focused on a specific task. You can encourage people to participate by giving them Starbucks cards or other perks. The outcome of nearly every test, Bob noted, is that you realize that some ass

Ed Marsh had me as a guest on episode 4 of his Content Content podcast, which is now available to listen to.

If you like podcasts, check out episode 4 of Ed Marsh’s Content Content podcast. Ed talks with me at length about a variety of tech comm topics — everything from how I got into technical writing to publishing tools, DITA, Jekyll, Markdown, and more. Chatting with Ed made me remember how much I like both listening to and recording podcasts. I think he’s given me renewed enthusiasm for recording more regular podcasts. Here’s the direct link to the MP3 file.

Writing good documentation requires you to set up a test environment and test all of your instructions -- testing the instructions yourself and against a user. Testing instructions can be time consuming and tricky, especially with developer documentation. It's hard to see past personal blind spots and assumptions. But testing instructions gives you access to insight that makes your documentation much more accurate and useful.

testing_documentation 1.1 Should QA test documentation? 1.2 Communicating feedback from testing documentation 1.3 Should technical writers care about more than documentation? 1.4 Should you add your testing scenarios into your documentation? 1.5 How do you test content that's beyond your skill level? You can download the MP3 file here. Testing overview Recently, in the rush to meet deadlines, I had to put aside one of the principles of technical writing I value the most: testing all the steps in my documentation, exactly as a user would. Walking through all the steps in documentation yourself, as a technical writer, is critical to producing good documentation. But the more complex setup you have, the more difficult it can be to walk through all of the steps. Especially with developer documentation, the tasks are not trivial. Still, they are essential to creating user-centered documentation. Step 1: Set up a test environment The first step to testing your instructions is to set up a test environment. Usually the QA team already has this environment in place, so sometimes all you need to do is ask how to access it. Get the appropriate URLs, login IDs, roles, etc. from your QA team. Ask them if there’s anything you shouldn’t alter or delete, since sometimes the same testing environment is shared among groups. Without this test environment, it will be really difficult to make any progress in testing your instructions. Although the test environment seems like a no-brainer, it really isn’t. A lot of times, developers test systems on their local machines, so setting up a web instance requires someone to get a server, install the latest build, and give you access to it. Other times the platform requires extensive architecture to set up. For example, you might have to build a sample Java app to interact with the system. Setting up these resources on your own machine may prove challenging. If you’re documenting a hardware product, you may not get a test instance of the product to play with. I once worked at a government facility documenting a million-dollar storage array. The only time I ever got to see it was by signing into a special data server room environment, accompanied by an engineer, who wouldn’t dream of letting me actually touch the thing, much less swap out a storage disk, run commands in the terminal, replace a RAID, or do some other task for which I was supposedly writing instructions. Many times the QA and engineering teams work on local instances of the system, meaning they build the system on their local machines and run through test code there. You may need to submit a special request for an engineer to put the latest build on a server you can access. Sometimes you may also have to jump over security hurdles. For example, connections to Amazon Web Services from internal systems may require you to go through an intermediary server. So to connect to the AWS test instance, you would have to SSL to the intermediary server, and then connect from the intermediary to AWS. You may also need to construct certain YML files necessary to configure a server with the settings you want to test. Understanding exactly how to create the YML files, the directories to upload them to, the services to stop and restart, and so on can require a lot of asking around for help. When you’re ready to submit a test call (assuming you have a REST API), you can probably use cURL, which makes it easy, but you’ll no doubt need to include an authorization in the header of the call. The authorization often uses a hash of a combination of factors. Can you see how just getting the test system set up and ready can be challenging? Still, if you want to write good documentation, this is essential. Good developers know and recognize this need, and so they’re usually somewhat accommodating in helping set up a test environment to get you started. For example, I asked an engineer to explain, step-by-step, how I was to connect to an intermediary jump host server

Introduction to technical writing -- slides and audio recording

The other week I gave a introductory presentation on API documentation to the East Bay STC chapter in Silicon Valley. Here are the slides and recording.

Slides API Documentation presentation to East Bay STC Chapter from Tom Johnson Here's the PowerPoint version of the slides. Here's the MP3 audio file: Links to more information This presentation is similar to other API documentation presentations I've given: TC Camp Workshop tc world India STC Eastern Ontario STC San Francisco

Recording and slides from "Jekyll vs. DITA: Bridging the Gap Between Tech Comm and the Web" presentation

Jekyll versus DITA 1.0 Check out Ed Marsh's podcast, and also My New series: Jekyll versus DITA 1.1 Authoring with Markdown in Jekyll versus Authoring with DITA in OxygenXML 1.2 Variables and conditional processing in Jekyll versus DITA 1.3 Creating re-usable chunks (conref) in Jekyll versus DITA 1.4 Building a table of contents with DITA versus Jekyll 1.5 Reviewing content in DITA versus Jekyll 1.6 Producing PDFs in DITA versus Jekyll 1.7 Creating links in DITA versus Jekyll 1.8 Final analysis between DITA and Jekyll 1.9 → Recording and slides from "Jekyll vs. DITA: Bridging the Gap Between Tech Comm and the Web" presentation Yesterday I gave a presentation to STC Berkeley about ways to bridge the gap between tech comm tools and web development tools. After talking about innovation patterns, I focused on static site generators, specifically Jekyll. I also explained how DITA compares to Jekyll. Slides Here are the slides: Audio recording Here's the MP3 audio file: Download MP3 (right-click and select Save As) You can download the MP3 file here. (Sorry, my attempts to record the screen using Camtasia failed -- Camtasia crashed. I think my MacBook Pro Retina display didn't jive with the old projector I was hooked into.) Links to more information Note that this presentation is similar to the keynote I gave at tcworld India. Personally, I felt the India presentation went better. If I were giving this presentation again, I would probably drop the DITA comparison, shorten the exploration of innovation, and just show static site generators in depth. Also see the Jekyll Versus DITA series for more detail about the tool comparisons.

Recording of API documentation workshop (REST and Javadoc) at tcworld India 2015

Recording of Innovation in Technical Communication keynote at tcworld India 2015

Innovation in tech comm 1.0 Sustaining and disruptive innovations 1.1 A long list of technical innovations semi-relevant to technical writers 1.2 The only significant innovation for tech comm 1.3 XML and the web: drifting farther apart? 1.4 The genius of Github and how it can transform tech comm 1.5 Microsoft and the last 5 great technological innovations 1.6 Piggybacking onto the innovation of the web 1.7 Some web tools worth using in help solutions 1.8 Static site generators start to replace web publishing platforms like WordPress 1.9 How to create a help API 2.0 Pushing content into any format with Jekyll 2.1 Slides for tcworld India 2015 presentations 2.2 → Recording of Innovation in Technical Communication keynote at tcworld India 2015 The following video is a recording of the keynote presentation I gave at tcworld India 2015 in Bangalore. In this presentation, I lay out a (hopefully persuasive) case for a new direction that tech comm writers can take in their tooling, arguing that the hotbed of innovation taking place today is with web tools and web platforms, not so much in the tech comm space, which seems to follow its own independent development track outside of web tools. http://youtu.be/dFN2XHcl6uY You can flip through my slides here: Or clone and fork the slides from Github here: https://github.com/tomjohnson1492/innovation. You can download the audio here: Download MP3 (right-click and select Save As) Summary The general outline of the presentation is as follows: Startups are great places to innovate. Innovation can be divided into at least two types: sustaining innovation and disruptive innovations. Disruptive innovations operate in the background as their technology matures; eventually they overtake the mainstream technology. Mainstream technology operates in a different value network and can't necessarily sink time and resources into research and development because they're too busy working on the next feature for their sustaining innovations. Innovation has a number of dilemmas — the time required to innovate can sideline your existing projects; you might have too much legacy content to make a change; you might not have the engineering background to build the tools you need; and you might be putting your career in jeopardy by investing in an obscure technology. There's a lot of pressure to follow the mainstream technology, especially DITA. I implemented DITA and worked with it for several projects, but eventually I found it too restrictive. Everything I tried to do required all kinds of hacks and workarounds. In looking in the space I was working in (API documentation), XML seemed to be an older technology not really used much. Instead, all the web developers are pretty much creating platforms that process HTML, Markdown, and JavaScript. REST APIs return responses in JSON (JavaScript Object Notation), not XML, and that communication protocol seems to reverberate throughout the web developer's toolchain. In looking at how people publish on the web, I noticed that many people use Github to share and develop code. Github is considered one of the most revolutionary technologies of the web. It allows developers to share, distribute, clone, and fork code, which gives rise to a lot of innovation. Developers don't work so much in isolation anymore. The code becomes living code samples on their local machine — you can continually update them as the origin gets updated. This phenomenon is referred to as "social coding." There's no reason why documentation can't be treated as code as well. Instead of working in binary file formats (which only computers can read), you can work with text-file formats, using a text editor (such as Sublime), committing your documentation to a code repository to share, version, and collaborate, and publishing via build scripts run on the command line. In fact, you can even create PowerPoint presentations in code. This presentation uses Reveal JS instead of PowerPoint. Everything

Podcast: The upcoming tcworld India conference on March 12-13, with Akash Dubey

I recently talked with Andrya Feinberg, a documentation manager and content strategist for Emotient, about best practices with API documentation. Below is a writeup Andrya has provided that summarizes some of the points she makes in the podcast. Length: 42 min. Download MP3 (right-click and select Save As) Here is Andrya’s summary of the best Continue Reading »