Tools for technical writers – the super-useful list
I’ll be speaking about API technical writing at STC Summit 2014. Part of the presentation is about useful tools for API technical writers. Since there are already some great resources on the Web about editors and IDEs, I plan to focus on a motley collection of “other” tools. Those that do a specific job very well. Those of which you’d say, “When I need it, I really need it.”
There are plenty of blog posts and articles about tools for documentation and code, including open source tools. Particularly when talking about editors and IDEs (Integrated Development Environments) most people have their favourites. The debates about which tool is best can get quite fiery!
Here are some useful links:
- Mike McCallister’s presentation, Open Source Tools for User Assistance. It’s well worth following Mike’s blog too.
- Chantel Brathwaite, writing on the TechWhirl blog about Technical Writing on a Shoestring.
- From Bret McGowen on the Rackspace blog, My Text Editor Final Four.
So, aren’t you going to talk about editors at all? 😉
My favourite IDE is Eclipse. I like to dabble in Android Studio and IntelliJ IDEA, just to see what’s happening.
Now that’s out of the way, let’s look at some super-useful and less-talked-about tools for API tech writers in particular.
Syntax highlighter for code samples
I frequently need to add a code sample to an HTML page, or include a slice of code in a presentation. Code is much easier to understand if the text is highlighted to indicate method names, variable declarations, and other syntactical essentials. And it just looks prettier too.
hilite.me converts a code snippet into styled HTML, which you can copy and paste into your page. Paste in your code, and select the coding language, to get the appropriate highlighting. Then click “Highlight!” to see the result. You can grab the HTML and CSS code, or copy and paste the highlighted text itself. You can even choose from a number of styles, such as “colorful”, “friendly”, “fruity”, and so on.
For example, I pasted in a Java “hello world” class, and asked for “tango” style highlighting. The “Preview” box at the bottom of this screenshot shows the result:
Testing web services and REST APIs
There’s an add-on for Chrome browser, called the Advanced REST Client, which I find very useful for getting examples of web service requests and responses. You can craft an HTTP request, then submit the request and see the response. This is a nice GUI alternative to a command-line tool like cURL.
Let’s say I want to use the Google Geocoding API to get a human-readable address for a pair of latitude/longitude coordinates. My URL would look like this:
I’ve pasted the above URL into the Advanced REST Client tab in Chrome, then used the add-on to expand the URL parameters, making it easy to see the composition of the HTTP request:
Now press the “Send” button to see the response. This is a partial screenshot:
Very handy indeed.
Chrome Developer Tools
The Chrome Developer Tools are a little tricky to grok, but once you’ve figured out what’s going on, they’re coolth personified. To find them, click the three-barred icon at top right of the Chrome window (the tooltip says “Customize and control Google Chrome”) then choose “Tools” > “Developer Tools”. The keyboard shortcut is Ctrl+Shift+I or Cmd+Shift+I.
A panel opens at the bottom of the page. It’s pretty busy, so take your time getting used to it. You can click an option to undock the panel and see it as a separate window, if you prefer that. In this screenshot, the DevTools panel is open at the bottom of the screen, and is showing the “Elements” tab:
There are many many things you can do with the DevTools. The Chrome DevTools documentation is a good guide. These are the functions I use most often:
- Check which CSS style is in effect on a particular block of HTML. This is particularly useful when there are a number of stylesheets at play. Sometimes the cascading effect of CSS doesn’t seem to follow the laws of gravity!
- Watch the error messages scrolling past on the “Console” tab. 🙂
- Edit HTML on the spot, to see the effect live on a web page before putting my changes into the source code.
Open Device Labs – Access to real devices and platforms for test-driving an app
It can be very difficult to try out an application on every supported device or platform. Especially for those of us dealing with mobile apps, there are just way too many devices out there for it to be feasible to have an example of each one.
One solution is to use emulators. But here’s an exciting initiative that I heard about recently: Open Device Labs.
The idea is that people may have last year’s mobile phone lying around, that they’d be willing to allow other people to use for testing. Some people may even want to donate new devices to the cause. Smart, enthusiastic people have set up hubs of Internet-connected devices at various locations around the world, and made them available to us all to use. For free!
I haven’t yet used a device from one of these labs, but the idea is awesome. What a great way to test an app, get screenshots, figure out the “how to” instructions you need to write, and just see how the user experience feels.
Mobile emulator in Chrome browser
With Chrome’s mobile emulation, you can make your desktop browser pretend that it’s something else. It can masquerade as an iPhone, Kindle, Blackberry, Nexus, and more. This is very useful for taking screenshots, and for seeing how responsive an app is to different device sizes and resolutions. The emulator is available via a fairly obscure setting in the Chrome Developer Tools panel.
Online source repositories are good for sharing code. In a tutorial, it works well to include code snippets and point readers to the complete source in a repo. Bitbucket and GitHub are very popular. I have accounts on both, because I’ve worked with teams on both. GitHub works with Git, while Bitbucket supports both Git and Mercurial.
That’s my list so far. If I find any more tools before the STC Summit in May, I’ll add them to the list I’m creating for my presentation. It will be fun to share them with the tech writers at the conference. Can you think of any super-useful tools to add to the list?
Posted on 2 February 2014, in technical writing and tagged api technical writing, Chrome developer tools, code samples, emulators, technical communication, technical documentation, technical writing, tools. Bookmark the permalink. 9 Comments.
Also worthy of mention that Firefox offers the same debugging tools as chrome (bar the device emulation) with a few super handy additions like the scratchpad.
Thanks Chris, the scratchpad looks super useful indeed!
The Open Device Labs sounds fantastic, indeed! Thanks for the find (and the link — I should update that prezo one of these days). Good luck at STC!
Thanks Mike! I’m looking forward to seeing a number of old friends and making some new ones. Hope to see you there too!
Sarah, you missed out emacs 😉 All the others look good to me though
LOL. I need a rhyme: ” I can get by in vi, … in emacs.”
Thanks Sarah, these are really useful suggestions. It might be worth mentioning that mobile device emulation is not available on regular Chrome – you need to download ‘Chrome Canary’ to get this tool.
Thanks for the post! The Google Chrome mobile emulation looks extremely useful. I was confused with the number of various parameters to configure, but then found the docs that explain many tricky aspects:
Also, I would add LICEcap to the list – a nice free screen capture tool that produces a GIF file as the output. GIFs are easier to use in online help as compared to video.
Thanks, LICEcap is an awesome addition to the list! The company, Cockos, looks pretty interesting too.