This content originally appeared on DEV Community and was authored by Segun Olumide
Introduction
Having a style guide is a very useful way of having a clear and consistent form of writing that can be improved over time. This guide is mostly useful for technical writers. I'll be sharing a few things I learned so far, writing for an open-source community (Fastify).
There are a few things you need to know and consider when writing your style guide.
1. Why am I writing this?
Even though it is necessary to have a style guide, knowing why can help you figure what needs documenting. Speaking with your community members, developers, or a lead (Could be a program/project manager or a developer advocate if there is one), can help you identify your organisation needs.
2. Who am I writing this for?
Perhaps, you want a style guide for open-source community members who contribute to existing documentations or intended 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 the time of reading through the whole thing before they realise it, even some may not figure it out eventually. Do 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 documentations. 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 Markdown.
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 improve 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 optimise storage and avoid the need to keep changing them when updates come up. 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 a writing style can help your reader know what type of document should be formal or informal. In my case, I find docs like references, terms & conditions in a formal tone, while guides, tutorials, and articles use a more friendly approach. Identify what writing style is needed before you conclude on which to employ.
Condescending terms
Condescending words give off a feeling of superiority to your readers. Using condescending tones are very sensitive. Words like "obviously", "him/he", "simply", or "master" are forms of condescending terms that can affect users who are not so confident or knowledgable about a particular topic. You might tend to lose them along the way. It's not a good reputation to let any of your readers 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, you can read an article by Carolyn Stransky - How to remove condescending language from the documentation.
Use of verbs
Verbs play a vital role in making the reader take action, and to take action, I mean to start your sentence with a verb. Highlighting when and how these verbs are applied can help improve the documentation, especially when it requires the user to take action. This approach is widely adopted in how-to guides because it requires the user to follow specific instructions.
Here's an example of where this can be used and compared to a less effective one:
Example:
Plain: To install all dependencies, you need to type in "npm install" in your terminal.
Use of verb: Open your terminal and type in "npm install" to install all dependencies.
Plain: 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 folder name "Back up" to save hard drive space.
Code indentation
If your documentation might entail 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:
- Two spaces
- Four spaces
- Tabs
Developers have been debating on which indentation is best. "Spaces" always take the win due to PSR-2 standards. If your team already have a standard they follow, then you can include that in your guide.
There are many more things to consider. This guide will put you on the right track. I hope this gives you some direction to making the most effective style guide for your team.
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
If you find this article helpful, a like from you will be awesome. It'll help push this article forward to those who might need this.
Happy writing and cheers.
This content originally appeared on DEV Community and was authored by Segun Olumide
Segun Olumide | Sciencx (2022-01-09T21:29:56+00:00) How to Create a Style Guide as a Technical Writer. Retrieved from https://www.scien.cx/2022/01/09/how-to-create-a-style-guide-as-a-technical-writer/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.