by Aaron Davis

Picking your battles as a consultant  Clip to Evernote

Yesterday, I received an email from an astute reader of our website indicating that a sample in our portfolio contained unnecessary marketing content in the introduction. He said;

Maybe it should go into some marketing material. You want to list the benefits of a product in its documentation to help explain how to use the product. This sentence seems to be trying to sell the product, which is already done.

The content in question was a single sentence in the introduction of a reference guide. Normally, I would agree in principle that marketing content has little use in a reference guide, API guide, data dictionary, and so on. In this case, however, we included it. Why? Continue reading →

by Scott Nesbitt

Staying on top of changes  Clip to Evernote

In the course of a software project, it’s not unknown for development to keep the folks writing the documentation in the dark about a new feature or changes to an application. This has happened twice on the project that I’m working on now, and both times it’s been annoying. I know that it hasn’t been deliberate but I’d prefer to keep in the know rather than scramble.

This blog post offers three ways in which you can make sure that developers keep you informed of all changes and new features. While I think that the third piece of advice — Look up the ladder — is a bit drastic and can generate animosity, it can definitely remind people to keep you in the loop.

by Scott Nesbitt

Bringing UNIX to your (Windows) desktop  Clip to Evernote

There comes a time in the career of many a technical communicator when they need to confront four dreaded letters: UNIX. For anyone used to the (relative) comfort of Windows, UNIX can be daunting. Cryptic commands typed into a terminal. Moving around strangely-named directories. Not being able to point and click. The horror.

Take it from me: UNIX isn’t all that daunting. With a little practice, you can quickly become proficient with the basic commands and concepts of UNIX. But how do you get that practice? If you have a spare computer lying around, you could try installing Linux or OpenSolaris. If you don’t, you can add UNIX to a Windows system with Cygwin.

According to the Web site, Cygwin is:

Cygwin is a Linux-like environment for Windows. It consists of two parts:
A DLL (cygwin1.dll) which acts as a Linux API emulation layer providing substantial Linux API functionality [and a] collection of tools which provide Linux look and feel.

It’s easy to install and gives you a perfect way to hone your command line chops. Best of all, Cygwin is free.

Aaron and I will be discussing Cygwin in a little more detail in a future blog post or podcast. Until then, give it a try and let us know what you think.

by Scott Nesbitt

Essential documents for a software project  Clip to Evernote

To the uninitiated, it can be shocking how much documentation a software project can generate — outside of manuals, help files and the like, that is. Design and test documents, specifications, architecture references, and more.

That said, there are many projects which have little or no supporting documentation. Why? The answer varies. With some projects, developers and project managers can’t be bothered putting anything down on paper. With others, they might not know what documents are needed up front. In a few cases, the supporting documentation is written after the fact. Strange but true.

So, what documents are needed for a smooth and successful project? This article outlines the documents that no project can be without. It might be useful to pass it on to development and project leads at the beginning of the development cycle.

by DMN Communications

Weekly links roundup  Clip to Evernote

  • Tom Johnson is asking “what’s the best thing you’ve done to grow your career?”
  • Peter Grainge offers some great advice on authoring, RoboHelp, and Flare.
  • New to technical communications, or thinking about it as a career, and wondering what the typical day in the life of a tech writer is? Here’s one perspective.
  • The curious might want to check out this comparison of DocBook and DITA.
  • An interesting look at Madcap Blaze.
  • Mike Unwalla at TechScribe has published a case study on reaching new markets with clear documentation.
by Scott Nesbitt

Naming your files: a few guidelines  Clip to Evernote

One thing that many of us, I’m sure, don’t think about is how we name our files. I don’t think anyone reading this goes to the extreme of tagging their files as file0001, file0002, and so on. But well-chosen file names make managing documents and their collateral a lot easier.

This post at TECHWR-L puts forward the following guidelines for naming files:

  • Use descriptive names
  • Use alphanumeric characters
  • Use underscores rather than spaces
  • Avoid numbering
  • Use short names
  • Be consistent

What guidelines do you follow when naming files? Feel free to leave a comment.