During our interview process, I had the pleasure to interview a candidate that had created the writing style guide used by a company with 50K+ workers.

As always, we explained the job description and some relevant details:

1. We are a team of four, working in an R&D with around 40 developers;
2. Our team’s ultimate goal is to make developers learn the OutSystems Platform in 0 seconds;
3. You cannot achieve this ultimate goal by creating videos, documentation, or whatever.

So as the interview went on, we wanted to access the candidate reading and technical skills. To test this, we asked the candidate to read a topic on how to deploy an application using one of the OutSystems Platform tools.

After a while he stopped reading and told us that couldn’t concentrate on reading the piece, since it was filled with errors and inconsistencies.

I cringed for a moment (I had written that piece), but then I was happy. This was the first person in several interviews that was able to criticize our work. Someone that was willing to openly criticize a potential employer. Someone that had an opinion and the guts to express it.

Wow. Maybe we had just found the right person.

Since we had already laid out some context, that we are a company with around 300 person, which is totally different that his currently employer, I thought it was time to dig deeper.

“How could we ensure those inconsistencies are detected and fixed” - I asked him.

He went on to explain that using a style guide would be a silver bullet.

“But I’m assuming a style guide is 200-400 pages long. If the topic you just read was written by a new hire, it wouldn’t help” - I continued.

He then explained that all new hires should read the style guide from cover to cover. And then read it again. Then they could start writing the help topic and later use a checklist to evaluate if everything was ok.

Since I could understand his point of view, I tried to understand if he really thought a style guide is a cure for all evils. So we gave him a challenge.

We are currently a team with only four members, and work inside the company R&D. The R&D currently has more than 40 people. We are developing lots and lots of APIs, which means that our team will not be able to validate the documentation produced for those APIs. Do you think we could convince our engineers to read the style guide, so that they create astonishing documentation?

He was disarmed. He told that developers are usually very busy people and usually preferred not to be interrupted (who does?). So the style guide would not work for this. Maybe creating a smaller style guide with just the essentials could solve our problem. Or just creating a self-evaluation checklist.

Documentation is a means to an end

The candidate was too focused on producing high quality and consistent documentation, that he lost focus on the essentials: documentation is a means to an end.

These should be your priorities: 1. Create a product that does not need documentation; 2. Document the features that are difficult to use; 3. Keep that documentation relevant and up to date; 4. Strive to make high quality and consistent documentation.

When you have to cut corners and make compromises (as I’m sure you’ll have to), you should start cutting from the bottom up.

If you cut the project budget, you’ll end up with something that requires documentation and product support. So in the long run you’re going to spend money on documentation and product support. These don’t scale as well as software does.

On the other hand, if you have invested in creating and iterating a product to make it easy to use, and cut corners on the documentation, will anyone notice? Have you ever noticed if your iPhone or Kindle documentation was inconsistent?

No, and why? Because they are so easy to use that you didn’t even bother to search and see if these products had documentation at all. On the long run, this ensures more users can use your software, which leads to higher adoption rates. It also ensures that you can do it without needing to scale your product support.

So when making decisions, make sure you choose the option that will save you time in the long run.

On style guides

Style guides ensure your documentation looks and feels consistent. It also frees someone from having to reinvent the wheel every time they start documenting a new project. But it has a tradeoff. It increases your team’s ramp-up time and you constantly need to remember everyone to use it. This alone can be a full-time job.

So they may make sense but you need to ask yourself if you really need one. If you work in a 4-person team, maybe you can get away with simple peer review or pair writing (programming?).