Tag Archives: API Docs

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!