Help/Reccomendations For Creating a Style Guide for a Knowledge Base

April 26, 2018 5:50 PM

I'm joining a team at my workplace that will be creating a knowledge base for our technical support staff. We provide support for domain/website management. We have a style guide that was gifted to us from another part of the company (cellular support) and it's pretty good. But I'm looking for any books that are helpful for creating this kind of technical knowledge base, for setting specific formatting standards and rules for our documentation team to follow when they create these internal documents/webpages. Other style guides that might be available on the web for us to model/mirror would also be appreciated.
posted by Fizz to Writing & Language (6 answers total)

I don't have a specific style guide answer, but my approach to this is first to remove unnecessary options, including free selection of fonts, colors, font size, boxes, etc. and giving folks simpler tools with a selection of preset styles, which are then enforced with CSS on the front end.

Is this an internal-only website? Are you using a tool that can prevent them from using unique styles? If they're using a WYSIWYG editor, can you hide the formatting tools you don't want? Limiting options goes a long way toward enforcing styles, in my experience.

Your approach to this may be different because you have a more technical audience, but my opinion is that in general, the longer the document, the less likely people are to actually read it. I tend to at try to condense my basic style guide down into Requirements (a few simple pages) and Recommendations (whatever's left), with the assumption that no one will ever look at the recommendations piece. That's not based on anything other than working with non-technical people for a really long time, though.
posted by cnc at 6:51 PM on April 26, 2018

For documentation guidelines, you might want to look at the Microsoft Style Guide, which is widely used in the technical writing world. It has a simple A-Z reference for terminology, plus more in-depth sections on common writing scenarios.
posted by neushoorn at 3:13 AM on April 27, 2018

Not specifically style guide related but you might take a look at A Book Apart.

Also, Brad Frost's Style Guide and others collected here on Pinboard.
posted by humph at 6:34 AM on April 27, 2018

This is probably way more than you are looking for, but I think anyone who writes in today's work environment would benefit from reading it: Typography for Lawyers.

It isn't just for lawyers. It is for anyone who has to produce professional documents. Much of text of the book is available as free excerpts on the author's website, and if you like it, you can buy a print version. He updates regularly when new issues arise. The author has opinions about things-- he is both a lawyer and a font designer. What a strange and great combination! Highly recommended.
posted by seasparrow at 9:10 AM on April 27, 2018

Maybe the O'Reilly Information Architecture book is also worth a look?
posted by carter at 12:26 PM on April 27, 2018

These are all very helpful resources, thanks friends.
posted by Fizz at 6:18 AM on April 28, 2018