Seeing things from the perspective of a learner
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.
Eight reasons why documentation fails for users, and what to do about it
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.
API documentation workshop opportunity at the STC Summit
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.
Lightning talks from San Francisco Write the Docs meetup
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.
Xeditor, a CMS editor for XML content
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.
REST API documentation workshop recording (STC Sacramento)
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 now available
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.
Hi there – Let’s get casual… Guest post by Lavanya Krishnamurthy
In this guest post, Lavanya Krishnamurthy explores the use of a casual tone in documentation as a way to give users a sense of having a conversation with the author. She presents several easy techniques for implementing a casual tone, and also notes the potential tradeoffs this approach can have.
Starting a new series on visual communication
The other week on Twitter I noted that, despite the power visuals play in communicating technical concepts, there's not a lot of good information out there on visual communication in the context of technical documentation. As a result, I'm starting a series focused on visual communication, somewhat like the series I wrote about API documentation. One benefit of publishing this info on a blog is that I can regularly publish small articles and benefit from widespread feedback to help me course-correct early and move towards more accurate information.
10 minute podcast on API technical writing with Ryan Weber on Stitcher
Ryan Weber, the Director of Business and Technical Writing at the University of Alabama in Huntsville, has a podcast called 10 Minute Tech Comm. In this podcast, he records short interviews with technical writing practitioners and innovators covering a wide variety of topics. Recently Ryan interviewed me for a podcast on API technical writing.
Retrospective — Looking back at the good and bad of previous experiences
As I move into my new job, one goal I have is to learn from the experiences at my former job and improve this time around. I want to avoid repeating the same mistakes but also remember to build on those things that worked. This post is a retrospective look at the good and bad of previous experiences.
So People Don't RTFM? Write a FM That's Worth R'ing — Guest post by Marcia Riefer Johnston
The following is a guest post by Marcia Riefer Johnston exploring an alternative view towards the RTFM argument. In this post, Marcia argues that it's the writer's care and interest in the product and users that leads to producing help content worth reading versus content that is mechanical, dry, and lifeless.
Lightweight DITA article in Technical Communication Journal
A recent article in the Technical Communication Journal explores lightweight DITA and the way it removes some of the complexity from the authoring process. Lightweight DITA is still in development, but it holds great promise in simplifying DITA and allowing authors to connect into larger systems for managing doc content without abandoning HTML.
subscribe via RSS