The Best Way to Document Web Apps?

Does a web application, or for that matter, any software application, really need documentation? If you ask the programmer who wrote the software, he’ll say yes — but it’s probably one of the last things on his long laundry list of items while marketing his product.

The users, on the other hand, are always the first to ask, “Where’s the help file? Doesn’t the application come with documentation?” Sometimes they’ll ask even before using the application or seeing the first screen. The programmer maintains and insists, “You see, it’s so simple and easy to use, it’s intuitive. You don’t need documentation. Geez, documenting means someone in my team didn’t do their job right. After all, people don’t read documentations before using Gmail or Flicker.”

My name is Sae, new member to the CATS team. I am the lead graphics/UI designer for CATS, and the above conundrum has been a constant issue for us. Should we strive to make CATS intuitive and easy to use and pay extra focus on usability, OR should we just build the UI and screens at our normal pace and let the technical writer explain them in the help file?

CATS Open Source Applicant Tracking System was designed to be intuitive and easy to use. We rely on the assumption that our users are computer-savvy, or at least know how to use a computer and the Internet. I mean, Human Resources hiring managers are already overloaded with work. Trying to read through a thick manual just to figure out how to use a product’s basic functionality isn’t top priority. Fact is — our users are busy; they don’t have time for hide-and-seek. Quite frankly, I never pay attention to those instruction manuals that comes with any product either.

Unfortunately, the newcomers to CATS are still confused about the application From the swarming demands for CATS documentation — or even just a quick guide — it has become crucial that we pay extra attention to the first-time user experience. We keep yelling telling users, “CATS is EASY. You don’t need documentation.” Well, that obviously didn’t work.

So, it was my task to create a quick guide. Initially writing step-by-step instructions in Word, we had planned to use Help & Manual to output the documentation into many formats. Thus a quick guide was born. But that still didn’t solve the problem. The quick guide was quick, but it was mundane and boring. After much contemplation, the CATS team has decided to move the instructional manuals to the new technological era — interactive tutorials!

The idea of documenting CATS wasn’t entirely scratched. Instead, we’re “upgrading” them to a higher and more meaningful level, which will please our users’ eyes, ears, brains and fingers. Thus began my quest for creating video demonstrations of CATS.

After plenty of research, I was faced with choosing between two screen capturing applications: TechSmith Camtasia or Adobe Captivate. Adobe Captivate was mychoice screen capturing software with its simple interface and usability. I have composed a recipe, or some tools, for making video tutorials that works for CATS.

Recipe for Good Video Tutorials for Your Software

  • Microphone – Any uni-directional built-in microphone with headphone would work. The headphone is needed for listening to audio. Some of the fancier microphone headsets have noise reduction/cancellation, which is really nice to have. We’re using Logitech’s Premium USB Headset 350 headset.
  • Quiet Space – Any space with closed windows and doors would work. We’re using our conference room.
  • Screen Capturing Software – Any screen capturing software will work. Adobe Captivate definitely won my vote for its capabilities.
  • Script – Any script written to include both video and audio components will work. Informal and conversational language works best.
  • Timeframe – Any time frame will work, but the shorter and more precise, the better. We are making our videos between 2-3 minutes.

For now, I have added the highly-demanded quick guide to our website. It can be accessed at the CATS support page

Et Cetera