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.
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.
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
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.
If you’re using OpenOffice Writer to create your tech docs (and there’s no reason that you can’t), you’ll be happy to know that OpenOffice 2.4.0 is now available. This release packs a number of great new features and enhancements, documented over at OOONinja. Some of the highlights of the newest version of OpenOffice Writer include:
- Enhanced PDF export to PDF/A-1 for future-proof document archival
- Support for relative links within PDF files
- Ability to import custom properties from Microsoft Word
- Improved localization support (10 new languages included)
Will this latest release help OpenOffice gain a little market share from Microsoft? And how favorable will these changes measure up against Word in Bruce Byfield’s next comparison study? Let us know what you think.
Marketing and technical writing. They’re at two ends of a spectrum. As a former co-worker once said “We deal with facts. Marketing deals in hype.” That might seem a bit extreme, but that’s the way it sometimes feels.
But in some circles, there’s a feeling that marketing should be involved in the creation of user manuals. I’ve heard a number of people, notably Kathy Sierra, argue that marketing should play an integral role in the the documentation process.
Darren Barefoot (with whom Aaron and I will be appearing on a DocTrain panel in May), on the other hand, disagrees. This older post explains at length why documentation should be kept out of the hands of the marketing department.
Darren makes one really solid point:
The user has already bought the product. They want to know how it works, not why it’s good. Often the people using the product are not the people who bought it. They don’t care why it’s good. They just want to know how (not why) it will make their lives easier.
In a few instances in my experience, the documentation that I’ve worked on has been used as part of marketing and sales efforts. The folks involved in pushing the software didn’t have a hand in writing the docs, but they did use the manuals and help to do what Darren mentioned: show potential customers what the application can do. In a couple of cases, the documentation played a small role in making the sale.