I'm trying to come up with way of providing more context for users in documentation. Providing context is essential to helping users understand how all the various pieces fit together. Without context, the information becomes fragmented and seems unorganized, maybe even random. I've tried a couple of approaches to establishing context -- consolidating the information more while I draft it, and also putting maps with signposts throughout the content. I still have a ways to go to figure this out.
Capture and display at a 1:1 ratio Zoom out on your browser’s magnification Capture from a Retina display Examples of Retina versus non-Retina screen captures Summary Technical writers take a lot of screen captures, often showing interfaces with both text and graphic elements. Usually these are partial screen captures that focus on the part of the screen they are highlighting. (By “screen capture,” I’m referring to captures taken ...
My slides and video for Jekyll Conf 2016 are available below. In this presentation, I talk about the various challenges I've had in using Jekyll for technical documentation. I explain my attempts to overcome requirements with everything from conditional filtering to generating PDFs, publishing across different environments, re-using content across projects, templatizing notes and alerts, and more.
I recently gave a lightning talk at a Write the Docs meetup in downtown San Francisco. My talk was titled Creating professional graphics in the easiest, simplest way possible. This post contains the slides, recordings, and other notes.
In this series on visual communication, I'm going to explore in a variety of topics in visual communication, such as screenshots, diagrams, concept illustrations, SVG graphics, translation, image file management, graphics programs, getting professional-looking images, images on mobile displays, print versus online images, design principles, and more.
Today I was thinking about the most important element in a successful technical writing career, and I think it's knowledge. The more you know, the better information you can write. There are at least three main types of knowledge: product knowledge, technical knowledge, and user knowledge. Just knowing one of the three won't provide you with the kind of information you need to write good documentation.
Alicia Avrach, a content strategist at ThoughtSpot, gave a presentation about video documentation at a recent Write the Docs San Francisco meetup. In this presentation, Alicia covers all the aspects of video production, from scripting to recording, post-processing, publishing, and more.
Sanborn Hodgkins gave a presentation to the STC Silicon Valley chapter called Shape of a Modern Technical Communication Organization on April 18. In the presentation, she highlights the variety of roles -- editor, videographer, information architect, content strategist, manager, writer, tools developer, and others -- that tech comm organizations need to thrive.
To write documentation that users find helpful, you have to understand the mindset of someone who doesn't possess all the knowledge that you have. You have to understand what it's like not to know -- even not to know some of the most basic assumptions. Trying to capture this state of un-knowledge and remember all the questions you have is critical to writing documentation that speaks to this type of user.
Good documentation is hard to write for a number of reasons -- operating systems, versions, technical abilities, and business scenarios often differ between tech writers and users. Products often evolve after the doc was written, since tech writers aren't always integrated with the team through the life of the product. Support and feedback channels don't usually route to the doc source, crippling the writer from valuable feedback. Finally, steps are often inaccurate, and tutorials are often focused too narrowly on isolated tasks, without addressing more end-to-end scenarios.
If you're planning to go to the STC Summit this year, or you're looking to get more information on API documentation, check out my pre-conference Summit workshop. I'm teaching a half-day workshop on REST API documentation. This will take place Sunday, May 15 from 8:30am to noon.
At the last Write the Docs meetup in San Francisco on March 29, we had 11 presenters give lightning talks. This post includes the recordings (audio + slides) of each presenter. There's also a compiled audio file in case you just want to listen to the audio. Lightning talks are a fun format that allows a lot of different members to present their own perspective and learning.
The following article is a sponsored article I wrote on behalf of Xeditor, which is one of the companies I advertise on my site. Xeditor provides an easy-to-use, Word-like interface for writing XML (either DITA or your own custom schema). You configure Xeditor to work with your CMS or CCMS, allowing authors across your company to contribute, edit, and review content.
I recently gave a workshop on REST API documentation to the STC Sacramento chapter. The workshop is about 3.5 hrs long and covers a lot of the concepts that I detail in my API doc course. In the workshop I first show you how to use a REST API like a developer. We then walk through common sections in API documentation, especially reference topics. Finally I give a tour of API documentation publishing tools.
Version 5.0 of my Documentation Theme for Jekyll is now available. This version allows you to associate different sidebars for different products on the same site. I'm trying to move away from the separate outputs model to provide a more web-friendly and integrated doc site experience that facilitates navigation across products on the same site.
