Shoap Technical ServicesThere is an unfortunate trend towards using more images and icons and using fewer written instructions (I like to say “words”). Personally, I don’t think it’s obvious what every icon actually is and what it means, especially when I’m in a hurry to do something.
Whenever I can squeeze an hour out of the month, I like to attend the TAG (Technology Association of Georgia) presentations of what they call technology “Rock Stars.” This past week, Val Rahmani from Damballa spoke about her experience moving from almost 30 years at a large corporation to running an internet security start-up.
As technical writers, we notice a lot of things that other people do not. I tend to notice too much because I’m a little too detail-oriented for my own good. But this can help improve whatever product, service, etc. I am documenting.
At Shoap Technical Services, we take pride in our ability to offer our clients fixed-priced bids for technical documentation and training. We feel that this is an advantage to our clients because everyone likes to know how much a project is going to cost before they start. And we feel confidant that we can correctly estimate a project because 1) we’ve done so many technical writing and training projects over the past 25 years and 2) we’ve learned how to break down a project into small enough parts so we can assign numbers (time) to each part to determine a total cost. What we like to say is, “If we can put our arms around the project, we can successfully bid it.” While we have, at times, missed our estimates and had to finish a project at a loss, most of the time we’re pretty accurate. That makes our clients happy because they know from the outset what they’re going to have to pay and it allows us to make enough money to stay in business.
A client recently asked us to take over the maintenance of a batch file specification she had been updating. She reached out to us because it was taking so much of her time to keep the document up to date.
As part of our proposal to do the work, we suggested that it would be better to convert the existing Word file into an HTML-based solution, such that there would be an HTML page for each XML element that was in the file. In that way, we argued, the developers using the material would have instant access to all of the information they needed when they needed it.
As a student of writing for well over 40 years, I’ve learned one thing: you can’t write about what you don’t understand. This is true whether the topic is Shakespeare’s contemporaries (my doctoral thesis topic), what you did during your summer vacation (a topic I never assigned when I taught Comp 101), or the attributes of an SQL database (which my company has recently done). Or perhaps a more accurate statement might be, you can write about something you don’t understand but no one will understand what you’re saying.
The first real question I get when talking to a prospect about technical writing or creating training materials – after the “personal” pleasantries – is “what’s it going to cost?” Of course, the question is usually qualified by “I know you can’t give me an exact price” or “I’m sure you’ll need a bit more information before you can quote the project” but bottom line, everyone wants to know how much they’re going to have to pay.
No surprise there.
The purpose of this training is to present an overview of the Work Management Process either as a refresher for existing employees or as an introduction for new employees.
The training is broken down into six lessons, each of which correspond to a particular step within the Work Management “Wheel.” Unlike a training course delivered via a learning management system, this training is completely open-ended so learners are free to explore and learn at their own pace.
Although this training is open-ended, some managers wanted their employees’ progress to be tracked to test their mastery of the content. Learners can directly link to a short quiz stored within an online learning management system from the Work Management Process Training site.
The original Work Management Process Training existed as a 180-page document that learners had to read. Once our Technical Communications project team got our hands on that, we all recognized that we had an opportunity to create a unique eLearning experience from this training.
The primary goal of the training site is to create an interactive, online resource that employees can visit to learn about the Work Management Process. Using a simple design, contextual links and actions, drill-down exploration of content, and leveraging interactive learning experiences, our training site easily stands out as a technology-based learning site unlike any other training initiatives we have created in the past.
Christmas, 2009:
The penguin wrapping paper is shredded from an oblong, rectangular package, carefully branded by a stark white apple on black monochrome — The Apple iPod ® Nano. The product is reverently lifted from the case along with the ear buds and sleek quick start guide, leaving the thick, intimidating, and unhelpful paper manual in the bottom — it might as well have been packing peanuts. Why do manufacturers bother with the archaic manual documentation which wastes paper, takes up unneeded space, and adds weight to the shipping fee? The product is blithely toyed with, prodded, poked, and explored without so much as a cursory glance to the woe begotten manual in the box, the user happily glancing through the quick start guide if they come upon any snags in the process of operating their new system. The manual is never read, collects dust, and slowly sinks into oblivion. Let’s explore why the manual falls to such a fate.
… we have come to value … working software over comprehensive documentation…
We don’t do a lot of work with practitioners of agile methodologies. I think that’s partly because there’s some built-in hostility towards documentation in the values of agile development. Of course, while the Agile Manifesto is referring mostly to documentation for the front end of the cycle (i.e., the giant FRS), that hostility ends up spilling over to end-user documentation as well. (I don’t think that was the intention.)