This content originally appeared on HackerNoon and was authored by Anna
This article contains information about creating the style guide:
- when it is beneficial;
- how to write it;
- which parts should be included in it.
Why Use a Style Guide?
Each professional technical writer has a unique writing style. This style is like a fingerprint, and it is visible in any content created by a human hand, no matter if it was intended to be a piece of art or a helpful guide. This style is shaped by many years of expertise, educational and cultural background, lexicon, and even current mindset.
\ However, any company wants to scale its business and avoid the situation when an employee becomes irreplaceable. It may be pretty expensive and time-consuming to rewrite all company documentation in case the technical writer left the job for good or just wanted to share the growing amount of tasks with a new employee. It can take ages to onboard someone new to the company.
\ Moreover, the documentation and all UI texts should have perfectly consistent terminology and at least a similar style. Basically, creating one's own style guide is a sign of a mature approach to documentation in a company.
Is it Beneficial to Use a Style Guide?
Using a style guide has a number of benefits:
- Common style of documents in the company.
- Easy onboarding of new technical writers.
- Automatic checks and other work automation.
- Scalable and interchangeable technical writing teams.
- Improved text quality.
\ Everything has its drawbacks, and the style guide is not an exclusion:
- Time and effort are used to create and keep the style guide up to date.
- As with any tool, using a style guide takes some mindfulness: paying attention to possible exclusions.
- Making new employees familiar with the style guide. This may take time and effort to set up some tests and onboarding procedures.
- Establishing proper processes, which involve reviewing documentation to match the style guide requirements.
\ All in all, a company will require some time to get used to it, especially technical writers and UI specialists. As a start, it may be a wise decision to make some presentations for colleagues who may be impacted by key features of a new style guide.
Using a Style Guide
Using the style guide might now be as straightforward as it seems. Use style guide as a strong recommendation: this helps to maintain its purpose. However, keep an eye on situations, when a style guide may be more of an obstacle, than a helpful tool.
\ For example, there are some situations to make a style guide a base, not a strict guide:
- You have a really specific document, which was not in mind when creating a Style guide. If you write a whitepaper, or maybe a general short article, you may use some style guide recommendations (using terms or capitalization rules, for example), but keep in mind the document's purpose. Later, you may want to create some guidelines for this type of document too.
\
- You have a document, that should be compliant with the style guide, but it has some specific terms or requirements that improve its understanding of the target audience. For example, it may involve using slang terms and acronyms, and certain ways of formatting text.
\
- You may have to adapt a document for certain purposes, for example, automatic translation. In this case, it may be more efficient to adapt the style guide to facilitate the translation process. However, if you don’t need to set up the process, it may be easier to avoid using certain style guide recommendations.
\ To sum up – be mindful and keep the balance between style guide recommendations and target audience comfort. The main purpose of the technical writer’s work is a customer’s benefit, keep that in mind as our main guideline.
How to Write a Style Guide?
A style guide contains a set of guidelines on the most important parameters of the document being created.
\ To write a style guide, get yourself familiar with two main things:
- Existing style guides of the industry leaders or top companies in your country.
\
- Understand the needs of the target audience. The style guide should make the documentation address these needs as precisely as possible.
\ Now, create a structure for the style guide. No need to make it perfect from the beginning – you can tune the requirements later, as you come up with great ideas.
\ In general, consider including the following parts in the style guide:
- Description of a brand voice. This will build a positive attitude towards the company brand.
\
- Terms, acronyms, capitalization conventions, and descriptions. This is important to make the whole document consistent in using the terms.
\
- Accessibility guidelines and inclusive language. This is important to make documentation comfortable for everybody.
\
- Grammar and language guidelines. This part is important to improve understanding for people of different backgrounds.
\
- Formatting and organization. Describes how to organize information in the document and how to format it to make it easy to find and easy to scan.
\
- Linking. Describes how to make links work.
\
- Content recommendations: instructions, lists, images, charts, tables, code examples, etc. This part is important to make documentation consistent.
\ It may be helpful to create a separate style guide for UI texts, as this type of text is very special and needs different guidelines.
\ Tune your style guide to the needs of your company and of your audience: the set of guidelines is totally customizable and should benefit your company brand and customer experience.
\ Keep in mind that the style guide should match the current requirements of your company and customers. This means, that you should review and update it in a regular manner. Remember, the style guide should serve your goals of delivering quality documentation, it should not be the obstacle in most cases.
Summary
To sum up:
- Using a style guide is highly beneficial in a company with more than one technical writer.
- To develop a great style guide, it is critical to be familiar with the target audience's needs.
- A style guide should be reviewed and updated regularly.
\
This content originally appeared on HackerNoon and was authored by Anna
Anna | Sciencx (2024-07-23T00:01:03+00:00) Style Guide in a Nutshell: What to Know. Retrieved from https://www.scien.cx/2024/07/23/style-guide-in-a-nutshell-what-to-know/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.