Last week, I created a video about the importance of having a style guide for your technical documentation. It helps to save time and stress, so that you are able to focus on more important things, like the quality of your documents. If technical writing isn’t your strong points, but you are pretty good with HTML and CSS, then using those skills will help you create an outstanding and effective style guide that will become the bible for the format, style, and presentation for all of your technical documentation.
Here is a sample of a CSS style sheet:
body{
margin:0px;
padding:0px;
font-family: Arial, Helvetica, sans-serif;
font-size:11px;
background:#000 url(images/bgr_main.png) repeat;
color:#3d3d3d;
}
#header_title h1{
color:#fff;
font-size:73px;
font-family:”Times New Roman”, Times, serif;
padding:10px 0 0 40px;
letter-spacing:-7px;
font-weight:normal;
font-style:italic;
}
.post-title h2{
font-size:27px;
color:#000;
font-weight:normal;
font-family:Tahoma, Geneva, sans-serif;
margin:0 0 10px 0;
}
.img.centered {
display: block;
margin-left: auto;
margin-right: auto;
}
As you see, you have to define every bit of your web site or blog, so that you can have uniformity. It’s the same with your documentation’s style guide.
Cover Sheet
You will usually have a cover sheet on all of your documents. The information that should go on the cover sheet is:
- Your Company’s Name
- Your Company’s Address
- Your Company’s Logo (Optional, but good. It will give an appealing visual for the reader)
- Your Company’s Point of Contact (This is if it’s going to be delivered to someone else)
- Submittal Date (The date the document is supposed to be delivered)
- Deliverable or Contract Number
- Confidentiality Statement (Optional. I don’t really care for these, but some companies have them for legal purposes)
A page border will make it look really nice, but this is something that is up to your discretion. Also, there should not be a page number. Here is a sample of a cover sheet I did for a proposal. I have removed my client’s information, but their logo, point of contact, company name, and address was on there as well.
Page Numbers
Page numbers are pretty easy. The cover sheet (as stated above) should not have a page number. All the pages before the Introduction of the document should be in roman numerals. These pages usually include:
- Table of Contents
- Table of Figures
- List of Tables
- Control Sheet (Optional. This shows the change history of the document. This is usually used for best practices, such as CMMI)
- Document Review Sheet (Optional. This page is where the chain of command signs off on it)
The document’s body should be numbers (for instance, 1, 2, 3, 4, etc.). If you have appendices, use the appendix heading letter, a hyphen, and the number. For example, if it’s “Appendix A,” then you will number them as A-1, A-2, A-3, etc.
Tip: The best way to separate the page numbers is by using section breaks.
Headings
Like I said in the video, you should try to go down six levels. Regardless of what word-processing software you use, they all basically behave the same way. You want to go to the Styles area. There you will see Heading 1, Heading 2, Heading 3, and so forth. You can modify them. You want to have an outline by using font size, font style, and numbering. For instance:
Heading 1 is using Arial, Bold, and size 14.
1 Introduction
Heading 2 would then be Arial, Bold, and size 12.
1.1 Scope
Heading 3 would be Arial, Regular, and size 12.
1.1.1 Document Scope Info
If you do this correctly, then it will automatically do the dirty work for you.
Text
You also want to define the text in your documentation. Usually it will be Times New Roman, and either be size 10 or 12. However, there are times that you have tables that the background is dark, then you will have to define the color as well.
Paragraphs
Paragraph spacing and indenting should be the next step in defining your documentation. You want to ensure that the spacing is not different from one document to another. It might seem like a small matter, but it really does a difference. You can decide that the spacing above a paragraph is 3.00″, and the spacing below is 6.00″. It shouldn’t be more than 9.00″ or it will make the document look weird. You could also indent the first sentence, so that the reader knows that a new paragraph is beginning as well.
Figures and Tables
Figures and tables should be the same size, margin, and heading. You usually want to separate the two because they are not the same. The figures could have a border surrounding them, while the tables don’t. Also, the heading for the tables could be above the table, but the figures below.
Conclusion
I probably missed bits and pieces because every documentation is different. However, these are the basics that will get you started. You want to ensure that you define everything, so that if a new person joins your team, then he/she is able to pick right up without asking too many questions.
