Choosing the Right Tools

Choosing the right tools is obviously important – but also hard, when recommendations emphasize unique selling points that make comparisons difficult.

My fellow German Marc Achtelig has put together three pages with criteria to help you choose the tool that does what you need:

The pages are very thorough and well thought out, but they don’t connect directly to products. As such, they’re great to help you make up your mind before you consult the pages of useful tools on his indoition web site. Or you can consult the HAT matrix and plug in all the features you’ve decided you need.

Marc also has a documentation quality check list which covers similar grounds (though shorter than a book can) as Gretchen Hargis, et al. in their book Developing Quality Technical Information.

As a bonus, all the information Marc has collected can be downloaded as a 100-page PDF.

Advertisements

Master change – with skills or attitude?

In the face of fundamental changes, skills seem to follow attitude. That’s my second conclusion from Sarah O’Keefe’s webinar about “Managing in an XML environment”. Read on for my summary of her argument and my comments. (Or see my previous post “Top strategies to embrace cost metrics” for more insights.)

Technical writers need a different skill set when moving to structured writing, topic-based authoring or an XML environment, Sarah explained. The general types of skills are the same as when writing “old style” books, such as user manuals: You still need writing skills, people skills, tool knowledge and domain knowledge. But the skills shift focus and application.

Shifting skills

Basically, Sarah argued, you need less tool knowledge and more of the other three skills – and better:

  • Writing skills focus on writing topics and their reuse. Writing topics requires more structure and better compliance to templates than book-like documentation which suffers free-form writing more easily. And topic reuse involves a lot of collaboration.
  • People skills enable increased collaboration. Colleagues may reuse, tweak and add to your topics. In fact, there’s no such thing as “your” topics, once they are subsumed into a larger collection of topics to which several colleagues contribute.
  • Tool knowledge decreases due to the separation of writing and publishing. Yes, you need to learn new tools, Sarah allowed, but that’s an initial effort. Much of the tool effort is split off into implementation and production of the documentation.
  • Domain knowledge steps in to sustain documentation quality. You can no longer hide behind the tools and improve specific parts of the documentation by layout or presentation.

Among all these changes, Sarah said, the biggest challenge is actually to come to constructive collaboration among writers. In a structured environment, the emphasis is on the process of writing and maintaining topics, not on the deliverable end product, such as a manual. Writers share responsibility for topics – which is very different from “owning a book”.

That’s why Sarah urged us not to “succumb to BOSSY, the Book Ownership System SYndrome” and to remember that “CROC is your friend” which stands for “Creating Reusable Objects and Collaborating” (somehow “CROAC” seemed a less appropriate acronym, I guess…).

Shifting attitudes

I agree with Sarah’s premise that topic-based writing requires different skills, with her analyses and her final recommendations. Yet I think the difference she describes is one of attitude rather than of skills:

  • Writing skills are different, not harder. I think it’s just as difficult to write a good, “old style” user manual as writing good topics. Writing topics seems to require more skills, because it’s new and different. I don’t think it’s actually harder, once we writers come to terms with its newness – and our resistance against it, however good reasons we may have.
  • People skills are overdue. I guess we tech writers feel the same pressure as many other professions: To collaborate, to heed stakeholders, to reach out to other teams and to connect to customers. If we notice the pressure more, it may be because we’ve worked in relative isolation. Mastering any change is much easier with a bunch of like-minded people than when you feel alone, stuck in the trenches.
  • Tool knowledge is overrated. Banking on tool knowledge isn’t the best career choice since your job hinges on a tool – and a specific version… When your tasks change, there’s the chance that your tool isn’t the best (anymore) for what you need to do. Tech writers should be really good at wrangling content (props to Scott Abel), not tools. If you distinguish methods and tools, I think you’ll find that it’s much faster to learn a new tool than to learn a new method, such as topic-based authoring.
  • Domain knowledge is second to content proficiency. While one can never have too much domain knowledge for a job, our key skill is to structure and relate that knowledge. I firmly believe that you should “always hire the better writer“, for two reasons:
    1. It helps your corporation to build up complementary skills: Your corporation probably has lots of domain specialists already – but how many really good writers does it have?
    2. In my experience it takes a year or two to become a decent domain specialist – but it takes longer than that to become a decent writer. (Though your mileage may vary…)

That’s why I come to a different conclusion. How successful we tech writers are when changing to a environment or processes depends less on our skills, but more on our attitude to them. There are at least two different ways we tech writers can regard our deliverables, our writing skills and our tool knowledge:

  • If they are our assets and define what we do, any change in environment and processes will threaten us.
  • If they are the results of previous learning, we can embrace change with the confidence that we can rise to the challenge again.

For example, when I feel I own a manual, any review, any editing has serious crisis potential already. I know what it’s like, I’ve been there… But once I feel shared reponsibility for the documentation at large, it takes on a more constructive, larger dimension, where we’re all in it together. Well, most of us, anyway… 🙂

Your turn

What determines how you face change: Your skills or your attitude? Can training and skills ensure buy-in for a new environment or processes? Or is it more important to have a self-confident, competent attitude?

Help smash tech writing dogmas!

I confess: I have a couple of dogmas about tech writing – though I generally consider them detrimental to communicative, collaborative jobs such as ours.

By dogma, I mean here a firmly held belief that I assume applies universally, if only because I haven’t been convinced otherwise yet… 🙂

However, seeing how much I’ve learned from your great comments and opinions to my previous posts, I’d like to invite you to chip away at my preconceived notions. Maybe my dogmas are unfounded and silly…

So here goes, meet two firmly held beliefs that I’ve acquired over the years:

Don’t build your own HAT!

I don’t care how cool you are as a software company, I firmly believe that you should not build your own help-authoring tool (HAT), unless that is actually (part of) your business.

True or false? I believe it’s true: The initial project to build the thing is like reinventing the wheel, but you may actually get all the cool features you think you need and don’t get from a third-party system.

But I’ve yet to see a company that can sustain the required maintenance efforts: Development for profit goes before development for internal cost centers, and just about anything goes before documentation. So dev resources for the HAT are always scarce and low-priority. As a result, bug fixes, updates and enhancements to the HAT take longer than they should. Meanwhile, writers work inefficiently and with frustration which often brings down the quality of the help.

I also doubt it makes economical sense to continuously invest non-billable development time when you can get a third-party product and maintenance plan, usually for a fraction of the cost.

Don’t buy a tool to fix your processes!

Blame your tools all you want for why your documentation is bad and/or painful to create, I firmly believe that getting a new tool won’t fix that.

True or false? I think it’s true: Frequently, bad tools beget bad processes, but you need to fix your processes separately. Problems with the tool can be so obvious, they tend to obscure ill-designed processes.

Actually,  I recommend to fix the processes first, so you can then buy the right tool that supports them. A good tool makes it easier and more efficient to create good results, but good pots and pans don’t make you a master chef.

Have at it!

Please help out a fellow tech writer: Leave a comment and give some reasons, if you think:

  • Dogmas deserve to die, and these especially!
  • Dogmas are generally bad, but these are actually true!
  • Dogmas rule, and we need more of them!

Portable apps for tech writers IV: Wrangling files and PDFs

By now you maybe know that I’m fond of portable apps. That I use them to write, take screenshots and look up stuff in dictionaries with them. But wait: There’s more! No matter how well I manage my contents and architect my information, sometimes files just go unwieldy on me. That’s when they come in:

My favorite apps to wrangle files

Now where’s that file again? Baregrep finds files by name, very quickly – much faster than Windows’ file explorer! And it finds text within ASCII files, again very quickly. It’s my favorite tool to find elusive entries in .txt files or help contents in .html or .xml files. Unix users will recognize the name: This is really a “bare” grep that also masters regular expressions. You’ll have to live with a nag screen upon startup, but, hey: It’s free…

Uh, how come there’s so many of them? Easy Duplicate File Finder finds, uhm: duplicate files. It compares not just file name and size, but contents, too! So when your “to read” folder has gotten too big again, it’ll point out that white paper which you’ve downloaded twice – with different names… It’s also great to clear out project directories where you may have created countless copies of files.

… and now without the spaces. Bulk Rename Utility comes recommended by reader JosephK. He writes: “Bulkrenaming of files with regexp expressions can be done with BulkRename. The interface takes some getting used to.”

For intrepid explorers. XYplorerFree is my portable file explorer of choice – and it’s not even double-pane. But I like it for its comprehensive file-finding and various display options, so I don’t mind that the last free version is almost 4 years old. If you want dual-pane explorers, try freeCommander and UltraExplorer, both of which rank highly. Or try some of the other file explorers in The Portable Freeware Collection.

Portable zipping. PeaZip is my archiving/compression tool of choice. It claims to handle 118 file types. At least, I’ve never had an archive type it couldn’t open. Be sure to grab the “PeaZip portable_standalone” package.

In sync. DSynchronize is a reliable file synchronizer with a straight-forward interface. You can preview what files will be added, deleted or overwritten before committing the changes. You can also opt to sync only newer files or to sync both sides. If you don’t like this one, try Toucan which is a bit fancier and also available from portableapps.com. (Remember that portableapps.com versions don’t require the portableapps.com platform – you can just point their installers anywhere…)

…got til it’s gone. CyberShredder removes files. For good. It overwrites them, up to 7 times. This can be useful when you want to be sure your files are not on the machine after you leave.

Going truly portable with PDFs

It’s a bit ironic that it’s called “Portable Document Format”, when it’s so difficult to modify PDFs – if it wasn’t for portable PDF editor PDFTK Builder. It lets you reorder, delete and duplicate pages in a PDF file and merge pages from multiple PDFs. You can also split a PDF into files with one page each. (Splitting and merging a subset, however, often gives you much larger file than the source, so it’s more like a first-aid kit for emergency surgery.) You can also rotate and stamp pages and protect your documents with passwords to read or change the documents.

If you just want to read PDFs on a fast, portable reader, I recommend Foxit Reader. Others prefer the even smaller Sumatra.

What tools do you use to wrangle files on the go? Feel free to leave a comment.

Portable apps for tech writers III: Dictionaries

I don’t just write and take screenshots with portable apps, I even use them to look up words, despite Wikipedia and countless online dictionaries. I like the seamless lookup from other applications with a click and don’t want to rely on being online. Fortunately, there are some very useful and usable apps out there. Here are my favorite portable dictionary apps.

“Lookup Central”, all in one

WordWeb combines a portable offline dictionary and thesaurus with tabbed browsing to look up words in popular web sites. Entries are displayed in two frames, with definitions and examples in one and the thesaurus in the other. (To see the full screenshot, just click it.) The free version of 30 MB comes with Princeton University’s WordNet wordbase of about 150,000 entries – and an unusual license agreement: “WordWeb free version may be used indefinitely only by people who take at most two commercial flights (not more than one return flight) in any 12 month period…” The paid “pro” version gives you more definitions and pronunciations, you can add online sites and buy extra dictionaries, thesauri and word lists. Click the screenshots to see a comparison of WordWeb and TheSage:

The “language reference system”

TheSage combines a portable offline dictionary and thesaurus with tabbed browsing… – Yes, just like WordWeb does. As far as I can tell, it even uses essentially the same wordbase. The main difference is the layout: You can expand and collapse the results by definitions, examples and thesaurus entries. You can also customize the online lookup sites. With 210,000 definitions taking about 20 MB, it has an edge over the free WordWeb version – if you can get used to the interface.

For a second opinion, the Freewaregenius has an older review of TheSage with a comparison to WordWeb in passing.

The multilingual dictionary

LingoPad translates words between German and English or other languages. I must admit this one doesn’t get much use when I’m online because WordWeb links straight to LEO. But it’s a reliable tool, especially when you’re mainly working in translations from or to German.

The classic dictionary bookshelf

Lingoes is a dictionary platform that lets you add all kinds of dictionaries. Of all the apps, it’s most similar to the long defunct Microsoft Bookshelf – which was, of course, neither free nor portable, but a cool solution in its time. Lingoes is a bit out of scope, though: Its license agreement limits use to “non-commercial purposes in non-business, non-commercial environments”, and it seems unclear whether the dictionaries download packages are properly licensed.

Which dictionaries do you use? Do you prefer online or offline?

Portable apps for tech writers II: Screenshots

Suppose you’re wise to portable apps and how to tweak text with them, with or without the apps mentioned in my previous post Portable apps for tech writers. But how about screenshots? Anything portable there? – Oh, good! I thought you’d never ask… 🙂

My top 3 portable screenshot apps

Top prize: PicPick Tools is my #1 screenshot app. It’s got everything I need: Quick and easy screenshots of desktop, window or screen area, quick change of output setting, auto-save to my project directory, a screen ruler and magnifier and a simple image editor. Most of the time, I take straight screenshots without call-outs, so I want an app that lets me do that quickly and keeps out of my way. PicPick does this best of all the screenshot apps I tried; it runs in my task bar. The problem with this is that, according to the product web site, the “portable version of PicPick [is] only for private, personal and not commercial use”.

Runner-up: FSCapture is very similar to PicPick. The problem with this is that it’s no longer a free app. The link takes you to the last free version 5.3 of February 2007 which works fine. However, it excludes some of the features baked into the latest version 6.5 and PicPick Tools, such as the screen ruler and sending captured images directly to Word, PowerPoint and an FTP server.

Honorable mention: The unpronouncable PrtScr affords the stylish whimsy of an animated preview. You need to see it to believe it – check out the video below. It’s great for quick and dirty screenshots with markups, but its emphasis on free-hand drawing and cropping makes it less suitable for pedantic operations. The problem with this (and you knew there had to be one) is that you pretty much have to create your own portable version by installing it, copying the program files to your portable directory or stick and uninstalling it.

[Update: I just remembered that freewaregenius has written up PicPick and PrtScr so you can get exhaustive second opinions on them.]

What do you think, is it worth to pay for screenshot toolsfor the extra features when freeware basically gets the job done?

Here’s PrtScr’s cool demo rock video:

Portable apps for tech writers

We tech writers can benefit a lot from portable applications: They make us more productive, especially with nitty-gritty tasks that Windows utilities and bloatware are not good at. They are free and easy to “install” and remove – just dump the application folder onto your hard drive or a USB stick. They can run wherever you have an open USB port. Portable applications can be our friends!

To learn more and to get started, PortableApps is the best place. Their PortableApps.com Suite with the most essential applications makes it extra easy for newbies. Or you just get the platform, which provides the start menu that sits in your task bar, and mix and match your applications. I’m now using the alternative Portable Start Menu, because I like its folder structure better.

You can get tried and proven portable applications from PortableApps. Or try The Portable Freeware Collection, though some of the apps listed there are a bit flaky: They might not be strictly portable, because they write to the registry. Or you may need to install them temporarily to create a portable version.

My favorite Windows-based portable tools for writing

A better NotepClipboardad: I use PlainEdit since I don’t do much coding. For plain text wrangling, it can’t be beat. You can convert text in more ways than I ever had use for, between special characters and HTML, between ANSI, ASCII and UTF-8. You can remove trailing spaces and lines containing certain characters. You can sort all lines from A to Z or inversely. And it can search and replace regular expressions.

If you are coding and want syntax support for programming languages, Notepad++ is your best bet.

Auto-complete text: With Texter, you type a shortcut and press a hot-key and out comes a common phrase or a product name: Type rtfm + Tab to get “For more information, please consult the user manual or online help.” Texter works system-wide, whereas Word’s auto-correct feature works, well, only in Word…

Add a history to your clipboard: ClipX will keep dozens of clipboard entries in a history, including images, even across sessions. This can also come in handy to retrieve accidentally cut text. (This one requires that you install it temporarily, so you can create a portable copy.)

“Paste Special” anywhere: You want to paste text from your clipboard, but without the formatting? PureText strips all formatting when pasting text. So it works like Paste Special in Word, but with a single hot key and anywhere in Windows. (This one is not strictly portable; it allegedly writes settings to the registry.)

Get text from system controls: One of the annoyances in Windows is that you can’t copy and paste system control text, such as a list of file names in Explorer or an error message. SysExporter helps you extract it – apparently with some exceptions, but it hasn’t failed me yet.

What portable applications do you use to tweak text? Your suggestions and comments are welcome!

P.S. This post is an updated, belated elaboration on my reply to the blog post Taking it with you by the guys at DMN communications from June 2008.