One of my fellow members of the Intermountain Chapter of STC is a major proponent of tech writers having project management skills. Planning is one of these skills.
I’ve thought for years that I’m not interested in becoming a project manager because the only writing they do is project plans. That kind of writing has held no appeal for me, and that’s probably why I’ve never seriously considered writing documentation plans before now.
Tom Johnson recently wrote about how the user education team in our organization is introducing a user education plan as part of the standard planning process for projects. He explains that he has come to support having this plan to fill out mainly because it will help him manage his time so he won’t be overwhelmed by work for various projects and then become unable to deliver quality products.
For me, the attraction of a user education planning document is to speak project managers’ language. They think in terms of budget, milestones, deadlines, requirements, and risks. A good user education or documentation plan will address these areas.
› Continue reading…
In our quest to get more decision-making weight in the organization, the User Education team is putting together a set of standard practices. You may wonder why we don’t already have these. To put it succinctly, we still have to carve out our place in the IT department’s project lifecycle so that at least most projects have a user education component to them. Since there have been only a few of us, we’ve operated mostly by our own judgment, each person doing what he judged appropriate for each project.
We’ve come to realize that if we want our department to take us seriously and give us the place we want, we need to be equipped to justify the decisions we make on what user education products are right for any given project. One of the things I’d like to see happen in our team is to develop a menu of products, each with a specific definition and an explanation of the situation(s) in which we would recommend that product.
I’ve taken a first shot at this. I’d like your help to flesh this list out, the descriptions, and the reasons you’d use each one. In the comments, please let me know what I’ve left out.
Quick Reference Guide: One-to-eight-page guide that contains reference information, repeatable tasks, or some combination of these. Used when users have small number of tasks or will frequently need to refer to charts, tabular data, and so on.
Quick-Start Guide: One or two sheets that explain the steps for setting something up. Could also provide a set of most common tasks. A throw-away document. Focus may lean toward one-time training.
Short Guide: Thirty-to-forty-page document that provides task steps and reference information. Used when there is too much information for a quick reference guide.
› Continue reading…
Eleven months ago—eleven months—Marc Achtelig emailed me about the resources for technical communicators on his site, indoition.com. I lost track of the email, so I publicly apologize to Marc for my lack of organizational skills when it comes to email. Thanks for your patience.
A few of my fellow tech comm bloggers posted back then about Marc’s site, so maybe it turned out to be a good thing that I screwed up, because Marc has updated his site. I took a look at his help authoring tool list, and I couldn’t believe how many there are. I hadn’t heard of most of these. But if you’re trying to put the strategy and the audience’s needs before deciding on the tool (in which case I salute you for putting things in their proper order), then Marc’s list is a good place to come to find a tool that fits the situation. Before you start, click Show/Hide Details to the right of the heading. That collapses everything so you can browse the basic types first.
The Choosing a Help Authoring Tool page gives some additional points to consider while you’re deciding on your tool, but these items are focused more on the author’s experience.
The HAT page isn’t the only page that lists software, though. There’s an entire list of software types or focuses in the nav column under “Useful Software.”
The quality checklist has some good questions to ask yourself while writing or editing. I particularly like the questions under “Tone, unambiguousness.”
I encourage you to take a look at Marc’s site. He’s done a thorough job of providing useful information for technical communicators.
Note and disclosure: This post is intended as a help for technical communicators and not as an advertisement of Indoition’s commercial services. Marc did add a link to this blog under Useful Websites > UA (User Assistance) and Technical Writing at some point (thanks!), which he offered to do in exchange for a post about his site.
I was hired by my current employer to provide documentation on a large and complex Web application to be used internally. After the main development phases ended, this project moved into maintenance mode. Developers, testers, and other team members were moved onto other projects.
Over time, other applications that we developed also moved into maintenance. Over the last several months, we brought in some developers and testers to fix bugs in and add small enhancements to these maintained apps. We also had a business analyst come on board to replace our previous one. He already knew a lot about some of our systems because he had worked on the original requirements.
The interesting thing about these developments is that I became one of the experts on our applications. When these new developers and testers came on, I was asked to give them an orientation on the applications. Since then, when they have questions, many of them have asked me.
Being the expert has led to a couple of small expansions to my role.
› Continue reading…
When I was in elementary school, I learned that it’s pretty much guaranteed that when answering true-and-false questions, if the statement contains any absolutes, it’s false. Notice I hedged there a bit.
The same thing is true when we’re talking about tools and technology in technical communication.
I see blog or Twitter posts sometimes that insist that some approach is the key or the only way to go. Sometimes, such statements are true—if they support such timeless principles as knowing your audience. But when they set forth some technology or technology-based approach to communication as the silver bullet that will solve all your tech-doc woes, I don’t buy it.
› Continue reading…
Journals by RSS
Journals by Email
