Site FeedPalimpsest has moved. Please visit our blog in its new location for the most recent posts from Scriptorium.
Palimpsest
Closeout sale on second edition of Technical Writing 101: now $12.95
Wednesday, August 19, 2009 — posted by Alan Pringle
We still have a few copies left of the second edition of Technical Writing 101. I want these last copies out of the office (how's that for truth in advertising?), so I have marked them down to $12.95. You can get free shipping within the U.S. when you purchase through our store.We're also offering the book for $12.95 through our Amazon.com store, but there is no free shipping there. (We're also selling slightly damaged copies at Amazon for $10.95.)
If you prefer to get the latest edition, you can download it in PDF format for $20.
Labels: book, technical writing
9:00 AM Permalink | |
In defense of English majors: we can understand business issues, too
Monday, July 27, 2009 — posted by Alan Pringle
In his latest blog entry, Neil Perlin explains how important it is for technical writers to have an understanding of business issues. With such knowledge, they can contribute to cost justifications for decisions that affect them directly. I couldn't agree more with that. It is absolutely in writers' best interests (and a matter of self-preservation) to understand processes and costs.I strongly disagree, however, with the following assertion:
Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions.I am an English major, and I freely admit I am more of a "words" person than a "numbers" person. That being said, I am no slouch in the finance department. (Calculus is another matter, though.) I know many people with degrees in English and the liberal arts who are quite adept at understanding The Big Picture and developing business cases. Lumping all of us into a "can rarely discuss cost-justification" group is unfair.
Now I need to remind myself not to group software developers into a "can rarely write a coherent procedure" category. (It's easy to make generalizations when you're not the target of them.)
Labels: business, cranky, technical writing
10:34 AM Permalink | |
Error message melodrama
Monday, July 20, 2009 — posted by Alan Pringle
The Shanghai Tech Writer blog has posted a screen capture of a rather ominous error message in FrameMaker:The licensing subsystem has failed catastrophically. You must reinstall or call customer support.I have never been the unfortunate recipient of that particular message in the many years I've worked with FrameMaker. If I did encounter that message, I would fully expect it to be accompanied by the shrieking strings from the Psycho shower scene. The use of "catastrophically" is a bit over the top. The fact I need to reinstall or contact customer support sets the tone enough, thank you very much--no soundtrack or scary adverb required.
The editor in me wants "catastrophically" removed from that message. If that bit of text came across my desk for review, I would have pushed back hard on the use of that word. It's bad enough the user has to get a solution to the error, and referring to the problem as "catastrophic" is certainly not doing the user any favors.
Labels: FrameMaker, humor, technical writing
2:38 PM Permalink | |
Printed version of Technical Writing 101 now sold at infibeam.com
Friday, July 17, 2009 — posted by Alan Pringle
The printed version of Technical Writing 101 (third edition) is currently available at infibeam.com, which provides free shipping to cities in India. At the time of this posting, Infibeam is offering the book for 1407 rupees (24 percent off the list price).Those who want instant access to Technical Writing 101 can download it in PDF format from our online store for $20 (USD).
Labels: book, technical writing
12:40 PM Permalink | |
Congratulations to contest winners...
Wednesday, July 01, 2009 — posted by Alan Pringle
...Bjørn Smalbro and Dave Truman, who will receive printed copies of Technical Writing 101.Thanks to everyone who entered the drawing. Even if you didn't win, you should have received an email with a coupon code for $5 off the PDF download of the book. (If you indicated that you teach technical writing, you should have received a code for a free review copy.)
Keith Soltys posted a review of Technical Writing 101 on his Core Dump blog yesterday. I'm pleased to report the review is positive.
A special alert to my fellow bargain hunters out there: Amazon.com is selling Technical Writing 101 at a steep discount. At the time I posted this blog entry, Amazon is offering the book for $23.73 (34 percent off the $35.95 cover price). The price does fluctuate, so who knows how long that discount will be in effect.
Labels: book, technical writing
1:27 PM Permalink | |
Enter soon: Technical Writing 101 contest ends tomorrow
Monday, June 29, 2009 — posted by Alan Pringle
We're giving away two printed copies of Technical Writing 101 (third edition) on Wednesday. Please enter the drawing before it closes tomorrow.We're giving away the books to celebrate the book's wider release to online bookstores such as Amazon.com, Amazon.co.uk, Amazon.de, Amazon.fr, and BN.com; you can also place a special order for Technical Writing 101 at your local bookstore. If you want instant access to the book, you can download the PDF version for $20 from our online store.
We achieved this wider distribution by working with another print on demand (POD) company, Lightning Source. We're quite happy with the quality of the books from our other POD partner, Lulu.com. However, at this time, Lulu doesn't offer distribution for publishers who use their own International Standard Book Numbers (ISBNs). We've released books under our own ISBNs since we published the first edition of Technical Writing 101 in 2000, and I frankly was not comfortable assigning an ISBN owned by a POD firm to content we developed. Using a publisher's ISBN would cause problems if we wanted to switch to another publisher later. We'd have to assign a new ISBN, and then the book would be in the marketplace with two different ISBNs. I wanted to prevent that marketing (and distribution) headache from ever happening.
I'm not going to write a long post about the virtues of Lulu.com and other POD publishers vs. Lightning Source because many other people have done that (in this blog post, for example). What I will say, though, is that Lightning Source is geared more toward experienced publishers, and Lulu provides more guidance that newer authors and publishers will certainly appreciate. If you want to get your feet wet in the POD pool, Lulu is a great place to start, but if you're a publisher who has published several titles with your own ISBNs, Lightning Source may be better suited for your needs.
Labels: book, print on demand, technical writing
8:05 AM Permalink | |
Win a printed copy of Technical Writing 101 (third edition)
Wednesday, June 24, 2009 — posted by Alan Pringle
As of this week, the printed version of Technical Writing 101 (ISBN 9780970473363) is available at online bookstores, and you can also special order a copy from your local bookstore. To celebrate the book's wider distribution, we're giving away two printed copies.Enter the contest by June 30 (next Tuesday). We'll pick two winners at random on July 1.
The printed book is now listed at many online stores, including Amazon.com, Amazon.co.uk, Amazon.de, Amazon.fr, and BN.com. (FYI to all you bargain hunters out there: some of these stores are selling the book at a discount and with free shipping, too.)
For those of you who want instant (and cheaper) access to the book, we're still offering the PDF download (ISBN 9780970473370) for $20. The download (which has been particularly popular with buyers outside the US) is available only through our online store.
Later, I'll write more about how we achieved the wider distribution of the printed version through our new print-on-demand partner, Lightning Source, and how Lightning Source compares to Lulu.com.
Labels: book, technical writing
10:01 AM Permalink | |
A different take on Twittering and technical writers
Tuesday, June 02, 2009 — posted by Sheila Loring
Technical writers abound on Twitter as do blog posts on how Twitter can make you a better tech writer.I'd Rather Be Writing has an alternate take in the article Following the NBA Can Make You a Better Writer. Tom Johnson uses the analogy of Kobe Bryant and Lebron James playing their respective positions on the court. He argues that unless you're a one-person shop, you're doing yourself a disservice by trying to be a Jack- or Jill-of-all-trades. Play up your strengths, and minimize your weaknesses, tech writers. Read Tom's article for more.
Labels: technical writing, Twitter
2:02 PM Permalink | |
Technical writing and social networks
Monday, June 01, 2009 — posted by Alan Pringle
There is an interesting thread on techwr-l about using social networking sites to deliver product information. In the thread, Geoff Hart notes there is a generation gap in those who turn to unofficial online resources vs. product documentation:The young'uns go to the net and social networks more than we older folk, who still rely on developer-provided documentation. We ignore this change at our peril. Cheryl Lockett Zubak had a lovely anecdote at WritersUA a few years ago about how she and her son both set out to solve an iPod problem; they both found the solution in roughly equal amounts of time, but she found it in Apple's documentation, while her son found it on YouTube.My experience as a user straddles both relying on official docs and information available elsewhere. When my iPod locked up a few years ago, I found decent information on Apple's web site, but the best resource for my particular problem turned out to be on YouTube. A user had made a video showing step-by-step what to do.
The dilemma of official docs vs. Web 2.0 information partially boils down to question of audience. As part of the process for planning and developing content, technical communicators should evaluate and remember the audience, and that audience consideration now needs to extend to how a company distributes the content. I don't think there are cut-and-dried answers here; for example, it's unwise to make the assumption that all folk over a certain age are unaware of or don't use social networks and other Web 2.0 resources. Ignoring unofficial information channels is certainly not the solution, however.
Labels: technical writing, web 2.0
10:40 AM Permalink | |
This weekend, get $5 off printed copies of Technical Writing 101
Thursday, May 21, 2009 — posted by Alan Pringle
Starting tomorrow through Monday, you can get $5 off a printed copy of Technical Writing 101, which is normally $35.95. To get the discount, use the code MEMORIAL09 during checkout at Lulu.com.Here is Lulu's fine print on the coupon code:
Offer valid on orders placed within the United States only. Enter code ‘MEMORIAL09’ during checkout and save $5.00 off any purchase of $25.00 or more. Discount cannot be used to pay for, nor shall be applied to, applicable taxes or shipping and handling charges. Promotional codes cannot be applied to any previous orders. No exchanges or substitutions allowed. Only one valid promotional code may be used per account. Offer valid from 05/22/09 through 05/25/09 at 11:59 PM GMT. Lulu.com reserves the right to change or revoke this offer at any time. Void where prohibited. Please note that coupon code is case-sensitive.
Labels: book, technical writing
7:26 AM Permalink | |
Get 10 percent off a printed copy of Technical Writing 101
Friday, May 15, 2009 — posted by Alan Pringle
If you have been waiting for a discount to purchase a printed copy of the third edition of Technical Writing 101, now is your chance. Through May 31, 2009, use the code MAYCONTEST10 during checkout to get 10 percent off when buying a printed copy from Lulu.com. The printed version is $35.95 (before the discount). FYI: the discount isn't applied to shipping or taxes.Technical Writing 101 is also available as a $20 download from our online store (but the Lulu discount doesn't work there).
By the way, if you received a coupon code for entering our contest, use that code now! The discount code expires today.
Labels: book, technical writing
12:25 PM Permalink | |
Technical Writing 101 contest: and the winners are...
Friday, May 08, 2009 — posted by Alan Pringle
Congratulations to Ravindra Kumar, Judy Walters, and Axel Regnet, who each won a free download of Technical Writing 101. As a thank-you to entrants who didn't win a free copy, we offered a $5 discount off the $20 price.All entrants should have received an email with a coupon code for a free download or $5 off. We appreciate your interest in our books.
Labels: book, technical writing
11:30 AM Permalink | |
Enter today: Technical Writing 101 giveaway ends tomorrow
Wednesday, May 06, 2009 — posted by Alan Pringle
We are closing our drawing for free downloads of Technical Writing 101 tomorrow. If you haven't already entered the contest, enter today. We'll pick three winners and notify them via email on Friday.If you want to sneak a peek at what's in the new edition, you can read the table of contents and excerpts from two chapters (PDF), and you can see the preview provided by Google Book Search. (Be forewarned that some pages in the Google preview weren't processed cleanly, but they are still readable.)
Labels: book, technical writing
11:59 AM Permalink | |
Technical Writing 101 is now available. Win a free download!
Wednesday, April 29, 2009 — posted by Alan Pringle
Technical Writing 101 (third edition) is now available for purchase! You can instantly download the PDF version from our online store for $20, or you can order a printed copy from Lulu.com for $35.95. We're also offering a site license for $250: you can download the PDF version and distribute it up to 20 people.To celebrate the book's release, we're giving away three downloads of the book. Enter the drawing by May 7. We'll notify the winners via email.
Enter the drawing today!
If you're an instructor and would like to review the book for your classes, contact us at books@scriptorium.com. In your message, tell us about the courses for which you're considering the book and how many students attend those classes each year.
Labels: book, technical writing
3:23 PM Permalink | |
Technical Writing 101: new edition, new approach
Wednesday, April 22, 2009 — posted by Alan Pringle
In early May, we will release the third edition of Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content. We published the second edition in 2003, so it was time for an update. A lot has changed in technical communication since then!You may have noticed a change in the book's subtitle: the previous editions' subtitles mention "Writing Technical Documentation," but the new edition focuses on "Writing Technical Content." We made that change because "documentation" conjures thoughts of printed manuals, which are no longer the primary form of output for many companies (or the new edition of Technical Writing 101, but more on that later). Because a lot of product information is now online, we added information about multimedia content to the chapter on visual communication, and we also revised the chapter on production editing to include information about reviewing online output.
Today's tech writers are handling more and more aspects of the technical publishing process; fewer companies employ full-time editors and production staff. The new edition—which is 44 pages longer than its predecessor—accounts for this shift in roles. Other big changes in the third edition include new content about DITA and Web 2.0. DITA's use has grown exponentially since we released the second edition, so it was essential for us to introduce DITA to prospective technical writers. The use of blogs, forums, and wikis has also had a profound influence on technical communication in the past few years, so we added a chapter that explains the impact of Web 2.0 technologies on technical writing. For more information about what's in the new edition, check out the table of contents (PDF, 135 KB).
Perhaps the biggest change for this edition isn't in the content: for the first time, we are releasing this title in PDF format. For $20, you will be able to download the new edition instantly from our online store. As with our other PDF-based books, the file will have no digital rights management (DRM) restrictions that prevent printing or that lock the file to a particular computer. Those who prefer a printed book can buy one in the near future from Lulu.com, which prints books on demand. A printed copy will be $35.95: the same cost as the second edition, despite the increased page count.
This is our first foray into print-on-demand books. After some number-crunching, we decided we did not want to print copies in advance and distribute them ourselves for this edition. Distributing your own printed book entails a lot of money and work: pay a printer to print and ship cases of books to you, store those cases of books, ship copies all over the world, deal with bulk returns from bookstores, and so on. We have seen a decline in the revenue from printed books (as have other publishers), so we thought it was time to try digital downloads as the primary method of selling the new edition of Technical Writing 101.
Many schools have adopted the book as a textbook since we released the first edition in 2000, and we hope the $20 price for the digital version will make it even more accessible to students—and to anyone who is considering a career in technical writing.
If you're an instructor and would like to review the latest edition, please contact us at books@scriptorium.com. We'll send you a coupon code so you can download the PDF version at no cost from our online store.
Watch this blog and our newsletter, Illuminations, for more details about the upcoming release.
Labels: book, technical writing
11:06 AM Permalink | |
How Twitter makes you a better writer
Wednesday, April 01, 2009 — posted by Sheila Loring
To Twitter or not to Twitter? That's the question many technical writers I know face these days. Critics say writing in 140 characters or less is ruining our ability to communicate effectively and follow grammatical rules.
In the following article, Jennifer Blanchard argues that Twittering actually improves your skills as a writer:
http://www.copyblogger.com/twitter-writing/
Labels: technical writing, Twitter
1:42 PM Permalink | |
Get $10 off two Scriptorium Press titles
Monday, February 16, 2009 — posted by Alan Pringle
We have just lowered prices on two books in our online store:- Publishing Fundamentals: Unstructured FrameMaker 8: Get both the printed book and downloadable PDF file for $39.99: that's $10 off the cover price of $49.99. (You can still download just the PDF version for $29.99.)
- Technical Writing 101 (second edition): Get the printed book for $25.95, which is $10 off the cover price of $35.95.
P.S. We're also offering discounts on these titles through our listings on Amazon Marketplace:
Labels: book, FrameMaker, technical writing
1:23 PM Permalink | |
What's happened to my local FrameMaker user's group?
Tuesday, January 13, 2009 — posted by Sheila Loring
The North Carolina FrameMaker User's Network (NCFUN), which became a STC Carolina special interest group, formed over a decade ago to support technical writers in the Raleigh/Durham area. Speakers (local and international) presented on everything from complex autonumbering and FrameMaker plugins to single sourcing and using reference pages. We usually had a topic for beginners and more experienced FrameMaker users.During the meeting, users had the chance to get advice regarding problems in FrameMaker. We also had the obligatory snacks and refreshments -- not to be underestimated, especially with one sponsor who always served delicious food.
The group also had its own mailing list. Users emailed questions between meetings, and we also sent meeting announcements to the list.
I write in the past tense because the group no longer meets. Over the years, attendance dwindled to a group of 10 and then 5 and then 3 regulars. It became more difficult to get speakers, and toward the end, the few regulars just talked (also not to be underestimated, but still...). I missed having this intimate FrameMaker resource. At every meeting, I learned something and had good geeky fun.
What happened? Did other FrameMaker resources become easier to use? For example, Framers is a very active mailing list with hundreds (maybe over a thousand) subscribers and anywhere from 5 to 20 messages a day. The group has a mailing list, whose archives are a bit difficult to search but are accessible through Google.
Did the time or location make the meeting difficult to get to, were fewer technical writers using FrameMaker, or did the topics no longer have wide appeal?
I suspect the answer is all of the above. Attendance at other STC Carolina special interest groups has also dwindled, and now none of them meet on a regular basis. Perhaps our members had too many groups to choose from each month and just gave up.
Ironically, now that I've been working on some non-FrameMaker projects, I'm less interested in the group, but I'd still like to see what other FrameMaker users are up to. Someone's always using FrameMaker in a creative way.
Have user groups in other parts of the world gone the way of the NCFUN?
Labels: FrameMaker, STC, technical writing, user group
9:59 AM Permalink | |
The case of the abused apostrophe
Wednesday, January 07, 2009 — posted by Sheila Loring
How often do you see abused apostrophes -- possessives punctuated as plural words and vice versa? We might know the rules, but it's easy to dash off an email and inadvertently use the wrong punctuation.Andrea Wenger wrote an article on how to use apostrophes correctly, even when style guides disagree. It's well worth the read: http://stc-carolina.org/newsletter/tiki-index.php?page=Obsessed+with+Possessives
Do you know what a genitive is? Read Andrea's article and find out. Fascinating stuff.
Shameless plug: For details on other issues technical writers are most concerned about, check out Scriptorium's Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation. Some topics include writing for an international audience, creating indexes, working with developers, and writing documentation plans.
Labels: apostrophes, punctuation, technical writing
4:22 PM Permalink | |
What I've learned as a member of the Society for Technical Communication (STC)
Tuesday, January 06, 2009 — posted by Sheila Loring
I've been a member of the STC Carolina chapter for over 10 years. During that time, I've volunteered in several positions and met a lot of people. Many of them also volunteered for the chapter. One problem we had was finding new volunteers. Many non-profits, in fact, face this problem. Organizations come up with ideas for programs or events that benefit members, but without volunteers, those ideas sit on the table.In a way, I couldn't understand why a technical writer wouldn't want to volunteer to do SOMETHING. I had fun. It's the best way to get to know other chapter members, plus I learned a lot professionally and personally. Here are a few examples of things I've done and what I've gained:
- FrameMaker SIG manager: Made contacts with FrameMaker users, practiced giving presentations, and picked up lots of tips 'n tricks.
- Competitions committee: Learned how to improve documentation and also discovered what NOT to do. Gained experience managing projects.
- Communications manager: Discovered that sending emails to a 300-member chapter exponentially increases your visibility. People really do read their email.
- Webmaster: Learned how to update web sites in both standard HTML and wiki formats and manage discussion lists. Gained experience juggling tasks, because I was communications manager and webmaster.
- Newsletter production editor: Currently my creative outlet and opportunity to learn how to write and produce publications via a wiki. I also get to do a little editing.
- Vice president: Learned how much work is involved in running a chapter!
- Chapter meeting participant: Learned about all aspects of technical communications -- from career development and writing in Simple English to single sourcing and online help development tools. Also learned how to be more outgoing -- go up and say "hi" to someone and chat. That was really hard at first but has gotten much easier.
I can't say that every minute has been completely enjoyable. Sometimes the newsletter deadline coincides with a personal crisis, and the last thing I want to do is hunt down graphics for articles. And you can't do everything! You'll WANT to volunteer to do several small things at once, which then amount to one BIG thing, and then life happens. You have a deadline at work or a family member has surgery. This brings me to the next lesson in volunteering -- learning how to say no.
So all in all, my experiences volunteering in the STC Carolina chapter have been very rewarding. I recommend dipping your toes in the water and trying something out. Email or call someone on the administrative council and ask what needs to be done. Start small. You might be surprised at the return on investment.
I'd love to hear about your volunteer experiences. Do share.
Labels: STC, technical writing, volunteering
3:40 PM Permalink | |
Murder by metaphor
Monday, January 05, 2009 — posted by Alan Pringle
The Shanghai Tech Writer blog has a hilarious list of awful metaphors written by high school students. These gems include:- Her face was a perfect oval, like a circle that had its two sides gently compressed by a Thigh Master.
- Long separated by cruel fate, the star-crossed lovers raced across the grassy field toward each other like two freight trains, one having left Cleveland at 6:36 p.m. traveling at 55 mph, the other from Topeka at 4:19 p.m. at a speed of 35 mph.
- They lived in a typical suburban neighborhood with picket fences that resembled Nancy Kerrigan’s teeth.
Labels: localization, technical writing
7:33 AM Permalink | |
Crosswords for technical writers
Monday, December 22, 2008 — posted by Alan Pringle
If you're looking to tease your brain during this holiday week, consider doing a crossword puzzle with a technical writing theme at the Crosswords blog. Never thought I'd see a puzzle with the clue "a family of transformational languages used to describe how to format XML files." I love the clue for 29 across: "to wield the red pen." That phrase should probably be the title of my autobiography. (My coworkers at Scriptorium can attest to that.)The blog also has another tech writing puzzle and the answer keys for both.
Labels: technical writing
8:20 AM Permalink | |
On the Unspoken Rule
Friday, December 19, 2008 — posted by Sheila Loring
Ben Minson at Gryphon Mountain Journals published an entry on the unspoken rule -- technical writers who don't read documentation. Admit it, you've been guilty from time to time. For me, learning to use a product on my own is an enjoyable challenge, one reason I'm a technical communicator. For a more complex product, such as the digital photo frame I just bought, I like to read the manual from cover to cover (or at least until the English translation ends), particularly if I'm teaching someone (hi, Mom) how to use the product.When technical instructions are sparse or unclear, several scenarios come to mind:
- The manufacturer doesn't value thorough documentation.
- As a result, an inexperienced (or non-) technical communicator wrote the documentation.
- The book was poorly translated.
- How long did the writer have to complete the project? Perhaps the development cycle didn't allow for sufficient screen shots or editing.
- How often did the product change throughout the writing process, so that last minute updates were missed? Even the best laid plans suffer when engineers tweak the interface or add new features one week before publication.
- Do you find evidence of inadequate single sourcing, for example, references to "earlier in this chapter"? The writer perhaps didn't have enough time to yank such references from an inherited book.
- Were the wrong tools used -- Word instead of FrameMaker? (Word might be fine for short, simple documents, not long, graphics-intensive technical documents.)
I'm not saying we shouldn't strive for complete, consistently formatted documentation. This is the goal of conscientious technical communicators even under the worst of circumstances. I'm saying sometimes the writer isn't completely at fault.
Labels: documentation, technical writing, unspoken rule
1:14 PM Permalink | |
We've been localised
Friday, November 21, 2008 — posted by Alan Pringle
Over the years, I have worked on manuals that were translated, and I have helped clients with their localization processes. Despite those experiences, I've never been part of a project in which US English was localized (well, localised) into UK English--until now.Cherryleaf has adapted material from our Technical Writing 101 book in its new Basics of Technical Authoring self-paced course. Cherryleaf is based in the UK, so the course is tailored for those accustomed to British English, but the content is helpful to any English speaker who wants to learn the basics of technical writing. Cherryleaf has also included exercises so students can get some experience applying the techniques explained in the course content.
(Full disclosure: Scriptorium is compensated for sales of Cherryleaf's course.)
Labels: technical writing
9:15 AM Permalink | |
Food for thought on document maintenance
Friday, November 14, 2008 — posted by Sarah O'Keefe
[Updated to add link that I rudely left out.]In a report from tekom (link in German), we hear about a session on translation reuse strategies.
The presenters point out one underappreciated risk of translation management -- language evolution. They note that as languages evolve, information stored in translation memory could become out-of-date. In particular, they noted that Polish has changed significantly in the past few years. (translation and paraphrase mine)
And today, there's an interesting article at Gryphon Mountain Journals. Ben Minson points out the conflict between writing content that is easy to maintain and content that is most helpful to the reader:
We need to learn to strike a balance between efficiency and usability. That said, most of the authoring environments I see have a long way to go before they reach "overly efficient" and need to swing back toward usability.Generic: “To turn on the machine, press the Power button.”
Specific: “To turn on the machine, press the Power button, which is located on the top of the device.” (…plus an image of the button, plus an image pointing out where on the machine it appears.)
Which one is easier to maintain? Which one is more helpful?
I’ll ask a different way. Which one is better for the writer, and which one is better for the audience?
Labels: conferences, localization, technical writing
8:30 AM Permalink | |
A technical writing ditty
Thursday, October 23, 2008 — posted by Alan Pringle
I'm constantly amazed by what you can find on YouTube, and this clip from a clever tech writer is no exception:Labels: humor, technical writing
9:21 AM Permalink | |
Know your audience, political edition
Tuesday, October 21, 2008 — posted by Sarah O'Keefe
Dear Sarah Palin,Your campaign schedule looks brutal. And since you're not flying commercial carriers, you don't even get frequent flyer miles. It's truly tragic.
Thank you for your personal letter. I have a few tips for you from the technical communication industry that should help you with future fund-raising attempts.
- Know your audience. I'm not sure where you got my name and address, but a quick cross-reference against the registered voter database would have told you that I'm registered as a Democrat. Based on that, you might want to modify "the fearful rhetoric of the Obama-Biden Democrats" to something a little less, you know, guaranteed to annoy me.
- Pruf your work. Really.
- Get my name right. "Sarah O. Keefe" does not fill me with warm fuzzies.
Your truly,
Sarah O'Keefe
PS Enjoyed your appearance on Saturday Night Live.
Labels: humor, technical writing
10:57 AM Permalink | |
The Golden Rule of technical writing
Monday, October 06, 2008 — posted by Alan Pringle
I stumbled upon a list of tips for technical writers, and I was glad to see tip 7:Understand Your Target Audience. Write and revise your content according to how your target audience thinks and understands things. Getting into their heads--knowing how their minds process information, how they might react, what they feel is important--allows you to customize your content to tailor-fit their needs.I would put that tip at the top of the list, but that's a quibble.
Sarah and I mention the topic of audience a lot in our Technical Writing 101 book; I think it is the most important thing for writers to remember as they create content. You can have an elegant XML-based publishing system that generates all sorts of output with the push of a button, but if your information doesn't address the needs of users, all the work put into the content and into the process itself is wasted.
That waste becomes even more acutely painful when a user abandons your information and finds helpful content on a blog, wiki, or forum. The contributors of that information probably don't know (or even care) that they followed the Golden Rule of technical documentation: Audience, audience, audience.
Labels: technical writing
2:53 PM Permalink | |
Free books are gone
Tuesday, August 19, 2008 — posted by Alan Pringle
We've given away all the copies of the Technical Writing 101 book. Thanks for all the responses.We are happy the books are going to readers instead of the recycling facility!
Labels: book, technical writing
1:16 PM Permalink | |
Yet more free copies of Technical Writing 101 (first edition)
— posted by Alan Pringle
As I mentioned in an update to my post yesterday, we located more copies of the first edition of Technical Writing 101. We have divided this lot into four batches, each of which has nine or ten books. If you'd like one of these batches, please contact me at books@scriptorium.com. We will ship the books to you at no charge.Update: We have given all the books away. Thanks for your quick responses!
Labels: book, technical writing
9:14 AM Permalink | |
Free copies of Technical Writing 101 (first edition)
Monday, August 18, 2008 — posted by Alan Pringle
We have 27 copies of the first edition of our Technical Writing 101 book. We are no longer selling that edition, so we are giving away our remaining inventory.To keep things simple, we have divided the books into three batches, each of which has nine books. If you'd like one of these batches, please contact me at books@scriptorium.com. We will ship the nine books to you at no charge.
Update: We have shipped all three batches. However, we think there are more copies lurking about. Stay tuned...
Labels: book, technical writing
8:26 AM Permalink | |
Is this the kind of advice we should give new tech writers?
Thursday, August 07, 2008 — posted by Alan Pringle
A recent blog post on getting that first job as a technical writer focuses quite a bit on desktop publishing tasks:I do not dispute having skills in different layout and illustration programs is a plus for a new tech writer. However, "organizing and formatting information" doesn't (and shouldn't!) take more than half of a project's time, particularly in today's smaller documentation departments with limited resources and tight budgets.For example, I always had an aptitude for graphics, page layout, font selection, and spatial organization. I always had fun playing around with different imaging programs like Photoshop and Illustrator, or page layout programs like PageMaker.
Yet I never thought about those skills within the framework of technical writing. Back then I wasn’t even aware that more than half of the time spent on a typical technical writing project does not involve actual writing but organizing and formatting information in two-dimensional work-space.
Taking time to figure out organization is essential, but spending a lot of time on formatting is a luxury and often unnecessary--especially in structured authoring workflows in which authors handle few (if any) formatting tasks. Even if you're working in an unstructured environment, a good template can automate formatting tasks so you can focus on getting the content right (which is a lot more important than getting it pretty, IMHO).
The blog post also doesn't take into account that a lot of content is single sourced these days: print, PDF, and many flavors of online help come from one set of files. Good tools can automate almost every aspect of the conversion processes for the various outputs, so there is no need to spend time formatting content.
In summary: having skills in all sorts of layout programs and illustration packages is helpful for a new tech writer. Having a basic understanding of how structured authoring solutions (including DITA) work is just as important--or even more so--for the next crop of technical writers. The days of desktop publishing for just print documentation are in the past.
Labels: technical writing
11:05 AM Permalink | |
Content creation isn't just for tech writers
Wednesday, February 27, 2008 — posted by Alan Pringle
We've seen an increase in the number of clients who need documentation processes that include input from part-time contributors (particularly engineers). XML-based workflows make it easier to handle this sort of input. Part-time contributors can enter their information into forms or can edit XML documents in an editor that doesn't require them to know a thing about publishing tools.UC Irvine seems to have picked up on this trend in collaboration: the school's extension program just announced a technical writing class for engineers:
“This course is designed to provide students with writing skills tailored for the science and engineering fields and to correct common problems,” said Jessica Scully, M.J., instructor of the course. “It covers the importance of writing for a particular audience, and applies journalism skills to help students effectively create a focused and concise document.”
The benefits of such a program go beyond engineering. Improvement in the quality of developers' writing would likely mean a reduction in the cost of creating a more unified voice in content (which in turn would lead to a smoother localization process). And last but not least, the end users (internal or external) would get better documentation.
This class could also help engineers gain an appreciation of the skill sets technical writers bring to an organization. That being said, it would be unfortunate if a company made the short-sighted mistake of thinking that sending engineers to a class like this would transform them into instant technical communicators.
Labels: technical writing
2:19 PM Permalink | |
TechCraft article: The secret to technical writing
Friday, September 28, 2007 — posted by Sarah
I contributed an article to TechCraft on technical writing.Here's the money quote:
As a technical writer, you must question authority.You can read the whole thing here (PDF).
[... Y]ou need to confirm all information, even when it comes from a person who outranks you, or has more experience, or is older than you.
Labels: technical writing
7:51 AM Permalink | |
Saturday, September 01, 2007 — posted by Sarah
In the past couple of weeks, I read an excellent post from Dave Kellogg about Facebook, and then received an invitation to join from a fellow technical writer.So I did.
Here are a few initial impressions:
- Facebook is much more compelling than LinkedIn (where I also have a profile). I find myself logging into Facebook to see what others are doing.
- I'm uncomfortable with a single profile for personal and professional use. At a minimum, I'd like the ability to label contacts as personal or professional and then control what information they see about me. Kellogg made a similar point in his posting.
Labels: change management, technical writing
10:09 AM Permalink | |
Buggy whips, anyone?
Thursday, May 17, 2007 — posted by Sarah
Jared Spool thinks that the technical writing profession is toast:
It’s no surprise that the two most popular topics at the [STC] annual conference are user experience and interaction design. Both are growing areas, while the art of writing manuals is going the way of blacksmiths and radio operators.
Technical writing won’t be gone until the last writer dies, but it will be curious to see what happens with the field as we move into a world where intuitive design implies a manual-less existence.
I don't think I agree with that last sentence. Most products have a LONG way to go before they get to intuitive. And furthermore, I don't think that technical writers are only producing manuals.
In the Trends panel at the conference, we touched on a related issue -- the rise of collaborative authoring such as wikis and user forums. Technical writers can and should play a role in the use of these tools to communicate with users. I also believe that animation and simulation will become more important. Although the upfront development costs are higher, localization costs are reduced (less text to translate!), and so these approaches are appealing for companies who deliver products in multiple locales. Another factor to consider is that visual communication does not require literacy.
Labels: technical writing
3:53 PM Permalink | |