Sections of this topic
There are quite a lot of questions about how a document should be designed. If the document projects an appealing appearance and motivates the user to want to read it, then the document has been properly designed. But how do we do this? A lot of these questions can be answered within a Style Guide. It will outline familiar or commonly used styles and formats that users have previously agreed upon. The amount of content presented in a Style Guide will depend on what is required for each document to be created.
- Try to denote only the important ‘must have’ items within the Style Guide.
- If it becomes too lengthy, break it up into sections and include a Table of Contents. It might even be more logical to break it up into more than one document. For example, if the:
- Style Guide is for Developers, you might create two different guides. Create a Style Guide for a document that details the format to use when requesting, compiling, and logging database changes and another Style Guide showing what style to use for coding documentation.
- Style Guide is for HR, you might need to create several, such as a guide for a document explaining how to complete certain forms, another guide for a document that explains procedures to follow, and another guide that explains the style to use when writing about company policies.
- Keep it organized; break up the guide by sections or subject matter.
What and how many Style Guides you create depends on the document type, project type, etc.
To help you begin, try to:
- Go back and track down previous documents and see how they were written and see what format was used the most. Also, note down inconsistencies.
- Create a chart to help you stay organized; use headers indicating various types of documentation versus the formatting and style used. Use this chart to give you an overview of what currently exists. Use it to also see where you can make the existing documentation more organized and efficient.
- Have a meeting with managers, project leaders, developers, users and those that will be using the Style Guides. Inform them of the Style Guides you will be creating and present examples.
- Communicate to them that each document created should have their own Style Guide.
- If you already have a draft of each type of guide, have them examine each one and then give a quick synopsis and see if they approve or disapprove of them.
- Show them the chart you created, point out the inconsistencies, and indicate how you came to the decisions you arrived at for creating better documentation.
- Explain how a Style Guide would allow a writer to focus on the topic and would save time and energy, as the writer does not have to think about how to format or style a document.
- You might face some opposition. They may want to keep some of the old formats and disagree with you. Listen to them, find out what they want and give them what they want. If you can, include what is desired, but indicate this as an exception.
This meeting is where you lay out all questions, uncertainties and reservations onto the table. This is the time to get all your answers. Also, if you have a pressing issue, ask it now. After the meeting, forward all attendees updated Style Guides to see if they meet with their approval.
Do not be discouraged. What will be in the company Style Guides will depend on the company and its culture.
If you have used Style Guides or created them, and would like to share some ideas for them, please leave a comment
