Enterprise Software

Create user-friendly documentation with this IT pro?s surefire tips

Have you recently been asked to write an IT support document? If so, you'll want to check out what this IT pro has to say about creating effective documentation before you put pen to paper (or fingers to keys, as the case may be).


While you may not be writing software manuals in the near future, odds are good that you will be asked to create some type of documentation during your IT career. During his years in the tech industry, IT pro and TechRepublic contributor Mike Hayes has created his fair share of manuals and cheat sheets. In this article, you’ll find out about one of his most successful projects and learn tips that you can use to make your documentation a hit with your end users—and peers.
Vital statistics

Name: Mike Hayes
Title: Design Engineer
Company: Cook Airtomic
Years in IT: 5
Age: 28

Most interesting job: Being team leader for the University of Louisville's Speed Engineering School Formula SAE race team
Certifications: BS and MENG in Mechanical Engineering
Home page on personal browser: v University of Louisville Formula SAE

Favorite TechRepublic features: Downloads
Hobbies: Formula SAE, computer gaming, machining
Favorite geek sites: v TechRepublic, Microsoft, sharkyextreme.com, www.tomshardware.com, www.driverguide.com


TechRepublic: Why did you decide to develop cheat sheets for UNIX?
Mike: I was somewhat new to UNIX, so I started documenting the commands as I learned them. This was my best solution for battling the "man pages." My cheat sheets were significantly quicker to reference than any other resource.


TechRepublic:
So it started out for personal use, but at what point did the project expand to include the rest of the company?
Mike: As my UNIX skills improved, I found friends and coworkers often asking for my help. I decided to clean up my notes and create a more formal document that I could give to others. Thus, the UNIX cheat sheets were born. My goal was to create simple, one-page printouts that someone could hang on their wall for quick reference. “Teach a man to fish,” as the saying goes.

 

See the UNIX cheat sheets for yourself
Click here to download Mike’s UNIX Command Cheat Sheets from TechRepublic’s Downloads Center.


TechRepublic: How many hours did it take to create your UNIX cheat sheets?
Mike: From beginning to end, I spent approximately 150 hours researching, writing, and simplifying the cheat sheets.


TechRepublic: What resources did you use to create the cheat sheets?
Mike: Books, help files, the UNIX "man pages,” and, of course, other techs.


TechRepublic: What tips would you give to other IT professionals for creating their own cheat sheets or other types of documentation?
Mike: Think of your audience. When writing the UNIX cheat sheets, I took special care to make sure they were written on a level with which other IT professionals would be comfortable. Write as though you are talking to your audience. Make your explanations detailed yet easy to understand. Remember to teach your readers as you would like to be taught. Above all, use the KISS principle: Keep It Simple, Stupid.

Think you've got the right stuff?
How can you be showcased in a Featured Member Profile? It's simple—just become an outstanding community member. Be an active part of TechRepublic by getting involved in discussion threads, posting article comments, answering Technical Q&A questions, and sending us feedback. If you're up to the challenge, click here to tell us your story.

 

About Bill Detwiler

Bill Detwiler is Managing Editor of TechRepublic and Tech Pro Research and the host of Cracking Open, CNET and TechRepublic's popular online show. Prior to joining TechRepublic in 2000, Bill was an IT manager, database administrator, and desktop supp...

Editor's Picks