Web sites and consultants  Clip to Evernote

web A few posts back, I wrote about some essentials for the consultant. Something that I deliberately left out of that post was a section about creating a Web site.

Whether or not a Web site is an essential is open for debate. I know a few freelancers and consultants who don’t have one and they’re doing well.

On the other hand, a Web site can increase your visibility. And it’s a great way for potential clients to view your work and learn more about you.

There are a number of ways that you can go about setting up your Web presence. Here are a few ideas.

Continue reading

A public statement of neutrality  Clip to Evernote

At least as far as the tools of our particular trade go. I’ve mentioned it in this space before, and this is my solemn declaration of my position.

Gordon McLean summed it perfectly for me when he wrote:

The tool is not important

And Adam Hyde of FLOSS Manuals expanded on that thought when he told me that he’s found that there’s a lot of tool fetishism in the wacky world of technical communication. I’ve felt that for a number of years, but it took someone from outside of our wacky world to articulate that feeling for me.

I’m not going to go into a long rant about tool and technology fetishism. It’s been done before. Consult your favourite search engine to learn more.

This is coming from a guy who, a decade ago, thought it was FrameMaker or nothing. How times and opinions change … I realize now what I always seemed to know: how you write and publish content pales in importance to the quality of the content itself.

FrameMaker, RoboHelp, Word, OpenOffice.org Writer, Flare, Blaze, AuthorIt, DocBook, DITA, WebWorks. Single sourcing, content-based authoring, component content management. All of them (and many, many other tools, techniques, and technologies) have their uses, their strengths, and their places.

I’m not going to ponder which one is better than another, or which is the best. I’m not going to stress over radical changes to the interface in a new release of a particular app. I’m not going to swoon over the latest fad or fancy in authoring techniques.

Instead, I’m going to do one of the few things that I’m really good at: I’m going to adapt as needed. I’m going to take advantage of my knowledge and experience. I’m going to learn. I’m going to use the right tool and the right techniques for a particular job.

And that’s what works for me.

Write documentation as if writing for the Web  Clip to Evernote

pen When I was in journalism school (and that was literally half a lifetime ago), the instructors constantly chivvied me and my classmates to write tight. That meant packing the most information into the least amount of space. It wasn’t easy, but when you did it, the result was like magic.

There’s a lesson there for technical communicators. I often compare tech writing with journalism. There are skills that bothjobs share, and the key to being effective is to keep what you’re writing short, to the point, and easy to read.

Continue reading

Weekly links roundup  Clip to Evernote

We’ll be returning to our regular blogging schedule next week. I hope …

The importance of process documentation  Clip to Evernote

processWhen you think of documentation, what probably comes to mind is user guides, online help, installation and administration documentation, and maybe API references. But one area of documentation that’s often overlooked is process documentation. In my experience, a considerable amount this type of documentation isn’t created/maintained by or in conjunction with technical communicators. Sometimes, it isn’t created at all. When it is created, the results and quality vary.

But process documentation is an important part of any project, and should be carefully written and maintained. I was reminded of this while poking around InformIT.com the other day. I stumbled across this article which “points out the importance of documenting your work and shows some ways to add true value to the process.”

The article provides an interesting approach to creating and maintaining process documentation. It was definitely an eye opener for me, mainly because I’ve never worked on process documentation. The article contains some ideas that I’ll definitely give a shot if I ever do work on that type of documentation.

Have you had any experience with writing and maintaining process documentation? If you have any tips, feel free to share them by leaving a comment.

Thriving on ignorance  Clip to Evernote

As you may or may not know, there was a FLOSS Manuals Book Sprint a few days ago to write a guide to the Linux command line. One of the participants (and organizers) was O’Reilly Media’s Andy Oram.

In a blog post, Oram discussed one of the more difficult tasks facing technical writers: “figuring out where to present background.” As Oram wrote:

What the authors need to understand is that readers don’t need to understand X before doing Y — usually.

Continue reading