FIAs (Frequently Ignored Answers)


I never liked the idea of FAQs. Even if they’re organized by subject, FAQs always fall short of real documentation. I often find that they’re a tease, a tiny glimpse into the workings of the system that don’t provide the information I need. FAQs are the Cliff Notes of documentation (Does anyone even remember Cliff Notes? You probably have to remember writing school papers in the pre-Internet days).

Once upon a time, FAQs really were a response to user questions that the system developers got tired of answering over and over again. Nowadays, I think they’re a lazy way for developers who don’t have time or interest to claim that they have documentation. I always get the sense that the questions were thought up by the developers/writers, rather than being real questions asked by users.

So, that’s why I’m inventing the much more practical idea of Frequently Ignored Answers (FIAs). These are ideas, procedures, strategies, and common sense that I find myself constantly repeating. Go thou and do likewise!

FIA #1: Strive for the fastest time to “Hello, World.” Kernighan and Ritchey revolutionized the software world when they offered the “Hello, World” program as their first sample app in the first chapter of their C book. Since then, smart writers have been following their lead.

There’s more sense to the concept than you might see at first. When you’re trying to learn a language or an API, your first task is to get your system set up to compile/build/interpret the language or link the API to your program. Writing a “Hello, World” program/app/whatever is a quick, straightforward task with an easily recognizable result. Your real goal is to get your system set up, and what better way to test it?

As a writer, developer evangelist, or software engineer, you must provide a language/API and tools that achieve a fast time to “Hello, World”. Five minutes to 1/2 hour is pretty good. More than a day is unacceptable. The developer’s inability to install the right compilers, libraries, dependencies, and so forth is no excuse. You have to anticipate these problems and provide documentation and tools that help the developer overcome the problem. It’s not the developer’s job to figure out your system; it’s your job to figure out your developer!

Advertisements

One thought on “FIAs (Frequently Ignored Answers)

  1. Andrew Davis

    Joe, I completely agree that TTFHW (Time To First Hello World) is critical. Many of my clients tell me they want a technical writer who can autonomously provide the essential elements, together with cut-and-paste’able code samples, that get the API user started. To these companies, the rest of what tech writers do — tools, strategy, best practices, non-dev doc — are irrelevant.

    Reply

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s