Introduction

Having a style guide is a practical way of having a clear and consistent form of writing that can improve over time. This guide is primarily helpful for technical writers. I'll be sharing a few things I learned so far, writing for an open-source community (Fastify).

You need to know and consider a few things when writing your style guide.

1. Why am I writing this?

Even though it is necessary to have a style guide, knowing "why" helps you figure out what needs documenting. Speak with your community members, developers, or a lead (Which could be a program/project manager or a developer advocate if there is one) to identify your organization's needs.

2. Who am I writing this for?

Perhaps, you want a style guide for open-source community members who contribute to existing documentation or for developers who write API documentation and requirements. Describing what the guide focuses on helps the reader identify which style guide to follow. You can save them time reading through the whole thing before they realize it. Some may not figure it out eventually. Make sure you include a clear description of the guide.

3. What should I consider when writing one?

There is a lot to consider when writing a style guide. Here are lists of things you may need to include in yours.

Guide requirements

A guide requirement tells the reader what they need to know before writing specific documentation. Take this example. A user finds an open-source project built with React Javascript framework they want to contribute to on Github but does not know the requirements needed. In this case, you can provide a requirement in a style guide that notes their need to understand specific tools and programming languages like Javascript, HTML&CSS and may also need to be familiar with markdowns.

Fonts

Your fonts determine the quality and standards of your documentation. According to Uwe R. Zimmer, good typesetting is the technical skill that enables your reader to take in your material smoothly, fast, and efficiently. Knowing when to use bold and emphasis, what font size to use, and how much line space is needed encourages better readability for your readers and improves the content design in general. If you want to know more about font selection, check out the 4 Basic Rules of Using Fonts Properly in a Technical Document by Ugur Akinci on medium.

Visual content

Some documentation doesn't require images. Most documentation tends to avoid Images to optimize storage and avoid the need to keep changing them when updates come up. However, it's okay to include them in product guides or documents that depend upon Images for a better description. You can also refer to an Image/Video linked separately (Youtube, Cloudinary, Vimeo.), which you can update without directly altering the docs.

Writing style

Including the writing style for specific documents can help separate formal and informal documents. In my case, I find docs like references and terms & conditions are primarily written in a more formal tone, while other guides, tutorials, and articles use a more friendly manner of writing. Identify what tone of writing is needed before you fully conclude with which style to use.

Condescending terms

Condescending words give off a feeling of superiority to your readers. Therefore, they are mainly red flags when using condescending tones. Words like obviously, him/he, or master are forms of condescending words that can affect your readers, especially when they are not knowledgeable about the topic. You don't want your readers to feel like they are too dumb to understand or feel it's not for them. You can include a list of words to avoid in your guide (example: use primary ✅, not master ❌, use they ✅ not him❌).

To get more insight, check out this article by Carolyn Stransky - How to remove condescending language from documentation

Use of verbs

Verbs play a vital role in making the reader take action, and to take action; I meant to start your sentence with a verb. Highlighting when and how to use a verb can help improve the documentation, especially when a doc involves the user taking action. However, it is mainly adopted in how-to guides because it requires the user to follow a particular instruction. Let me give you an example of where this can be used and compared to a less effective one:

Example: To install all dependencies, you need to type in "brew install node" in your terminal.

Use of verb: Open your terminal and type in "brew install node" to install all dependencies.

Another example: There is a need to delete the folder called "Back up" so that the hard drive space can be saved.

Use of verb: Delete the "Back up" folder to save hard drive space.

Code indentation

If documentation involves some form of code examples, providing a standard indentation style is essential to keep your code structured, neat, and consistent. There are three indentation styles I know of, which are:

• 2 spaces
• 4 spaces
• Tabs

Developers have argued on the most effective indentation, and spaces take the win so far due to references in PSR-2 standards.. If your team already has standards they follow, you can include them in your guide.

I wanted to make this as short and direct as possible. Of course, there is more to what I pointed out, but I hope this gives you some direction to make your team's most useful style guide.

Here are also some pointers that can help:

• Gatsby style guide
• Google developer documentation style guide
• Write the docs
• Apple style guide
• Microsoft writing style guide

❤️ this, if you find it helpful. It'll help push this article forward to those who might need this.

Happy writing and cheers 🥂.