Style Guide

General

Existing styles should be used for nearly all components on the site. This page lists common styles. If inline styles become necessary, consider creating a standardized component to handle it.

Where possible, use lists and headings to provide information at a glance for readers who are skimming the page. For spacing between paragraphs and sections, do not use hr tags or spacer divs. Nearly all spacing needs should be met by using sections (with class “bwc-block”)and paragraph and heading tags.

Headings

Headings indicate site structure visually, and also provide important search engine information. Users often skim a page by its headings. It is important to use headings to show the document structure.

Heading tags should be uniform throughout the site. Do not apply additional styles, colors, sizes, etc. to heading tags. If a new style of heading is required, that style should be incorporated into this style guide and the site’s stylesheet.

Correct
<h1>10 Guidelines for Technical Writing</h1>
Incorrect
<h1 style="font-size: 40px; color: blue;">10 Guidelines for Technical Writing</h1>

Heading 1

<h1> tags should occur only once on the page. The <h1> tag describes the content of the entire page.

Heading 2 to Heading 6

All other heading tags should indicate progressive levels of content nesting. An <h3> tag should not occur without a preceeding <h2> tag and so on.

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6
                            
<h4>Heading Samples</h4>
<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>
<h5>Heading 5</h5>
<h6>Heading 6</h6>
                            

Guidelines

When a page contains a series of guidelines, use the guideline component before the heading tag.

Comma Rule 2:

Use commas to separate three or more elements in a series.

                            
<p class="guideline">Comma Rule 2:</p>
<h2>Use commas to separate three or more elements in a series.</h2>
                            

Sections

Each section of content should be enclosed within a <section class="bwc-block"> tag. This tag provides for a bottom margin to separate sections of text. In general, if you have a new <h2> tag, you should probably start a new section.

            
<section class="bwc-block">
    <h2>Section 1 Title</h2>
    <h3>Section 1 Subtitle</h3>
</section>
<section class="bwc-block">
    <h2>Section 2 Title</h2>
    <h3>Section 2 Subtitle</h3>
</section>
            

Blockquotes

When a quote is pulled out from content on the page, use a blockquote component.

Readers more often felt the documents using common, everyday words were written by writers who were more intelligent than the writers of the documents containing difficult, archaiv words.

Someone famous in Source Title
                            
 <blockquote class="blockquote bwc-blockquote">
    <p>Readers more often felt the documents using common, everyday words were written by
    writers who were more intelligent than the writers of the documents containing difficult,
        archaiv words.</p>
    <footer class="blockquote-footer">
        Someone famous in <cite title="Source Title">Source Title</cite>
    </footer>
</blockquote>
                            

Links

Link text (the part you can click on) should be relevant to the destination. Incorrect: “We offer a range of business writing courses. Click here to learn about our courses.” Correct: We offer a range of business writing courses.” Read more links should usually say simply “Read More” and should not contain parentheses or other characters. There might be times when a “Read More” link should be more descriptive. When the destination is more prominent than a simple link or serves as a call to action on a page, use a button.

Citations

When an external work needs to be cited, use the citation component as outlined below. The actual cite tag should surround the title of the work.

* Oppenheimer, D. M. (2006). Consequences of Erudite Vernacular Utilized Irrespective of Necessity: Problems with Using Long Words Needlessly, Applied Cognitive Psychology, 20, 139-156.

                            
<p class="bwc-citation"><sup>*</sup> Oppenheimer, D. M. (2006). <cite><a href="#">Consequences of Erudite Vernacular Utilized Irrespective of Necessity: Problems with Using Long Words Needlessly</a></cite>, Applied Cognitive Psychology, 20, 139-156.</p>
                            

Examples

When an example that is only a few lines is desired, use the example component. For longer examples consider using the long comparison component.

Example
10 Guidelines for Technical Writing
                            
<dl class="bwc-compare">
    <dt>Example</dt>
    <dd>
        <p>10 Guidelines for Technical Writing</p>
    </dd>
</dl>
                            

Short Comparison

When page content includes a comparison with short titles and just a few lines of text, use a short comparison component.

Correct
10 Guidelines for Technical Writing
Incorrect
10 Guidelines 4 Technical Writing 🙂
                            
<dl class="bwc-compare">
    <dt class="bwc-correct">Correct</dt>
    <dd>
        <p>10 Guidelines for Technical Writing</p>
    </dd>
    <dt class="bwc-incorrect">Incorrect</dt>
    <dd>
        <p>10 Guidelines 4 Technical Writing :-)</p>
    </dd>
</dl>
                            

Long Comparison

When page content includes a comparison that is more than a few lines of text, or where the title is longer than a few words, use a long comparison component. Do not use more than 3 columns in a single card group.

Comparison text often contains titles. For example, the text might say “Too general.” If there is no title for a block of long comparison text, simply use the titles “Correct” and “Incorrect”. There may also be times when a correct/incorrect title in not apprproate. In either case the title should be wrapped in a card-title and bwc-correct/incorrect div. See the examples. In that case simply do not include a title.

Example

Too general

Problems arose in a number of areas of the device that required intervention by a qualified member of staff so remedial action could be taken.

Too much detail, using complex vocabulary

Monitoring the temperature saw a rise from 80.5 degrees Fahrenheit to 124.5 degrees Fahrenheit causing problems in the equipment temperature since the equipment was not created for temperatures in excess of 105 degrees Fahrenheit, a temperature that creates a molecular breakdown of the components. As the optimum operating temperature is 80 degrees Fahrenheit, the result was an expansion of the component part beyond its maximum operating temperature level of 105 degrees Fahrenheit. This in turn led to a failure of the switch that was rectified by the engineer who assessed that the cooling coefficients needed with a possible ambient temperature above the manufacturer’s recommended levels were more in the range of 80 to 90 degrees Fahrenheit.

Three reduced settings were considered, namely reducing the inflow of current by 10%, 20%, or 25%. These would lead to a reduction in the traffic by 13%, 18%, or 32%.

The optimum setting was 25.32% of the 80,000 maximum number of transactions per hour rate, which was achieved by reducing the number of transactions, relaying the overage to other components and switches. The engineer then had to replace the component and reset all of the relevant switches.

Specific and concise

Because of a sudden increase in transactions, the temperature in the component rose to 124.5 degrees Fahrenheit. The component’s parts overheated, causing the switch to fail. To keep the transactions flowing through the system, an engineer replaced the component, reset the switches, and diverted transactions to other components. That reduced the number of transactions by 25 percent, returning the temperature to the optimum level for this component.

Example

Correct

Problems arose in a number of areas of the device that required intervention by a qualified member of staff so remedial action could be taken.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla vitae dui quis eros mollis tincidunt ac vitae tellus. Curabitur quis sem et diam sollicitudin dignissim et sed neque. Etiam id diam nulla. Vivamus consequat volutpat nulla, at ornare orci pretium sed. Duis massa ex, facilisis at auctor eget, tempus ut nibh. Nulla lobortis nisl a lorem semper, id ultricies lectus vehicula. Nunc sed quam nisi. Praesent erat turpis, aliquam et massa a, tristique feugiat purus. Mauris egestas, elit et viverra facilisis, ipsum ipsum varius lectus, in mollis augue ipsum sed mi. Nullam aliquet nibh feugiat erat luctus ultricies. Sed interdum mauris non neque pellentesque viverra. Integer faucibus nunc ante, vel lacinia turpis tincidunt vel. Pellentesque maximus dictum rhoncus. Sed a mauris cursus, tempus quam posuere, placerat sapien. Fusce aliquet iaculis justo, vitae feugiat magna sodales id.

Example

Incorrect

Duis massa ex, facilisis at auctor eget, tempus ut nibh. Nulla lobortis nisl a lorem semper, id ultricies lectus vehicula. Nunc sed quam nisi. Praesent erat turpis, aliquam et massa a, tristique feugiat purus. Mauris egestas, elit et viverra facilisis, ipsum ipsum varius lectus, in mollis augue ipsum sed mi. Nullam aliquet nibh feugiat erat luctus ultricies. Sed interdum mauris non neque pellentesque viverra.


<p class="example">Example</p>

<div class="card-group">
    <div class="card">
        <div class="card-body">
            <p class="card-title bwc-incorrect">Too general</p>
            <p class="card-text">Problems arose in a number of areas of the device that required
                intervention by a qualified member of staff so remedial action could be
                taken.</p>

        </div>
    </div>
    <div class="card">
        <div class="card-body">
            <p class="card-title bwc-incorrect">Too much detail, using complex vocabulary</p>
            <p class="card-text">Monitoring the temperature saw a rise from 80.5 degrees
                Fahrenheit to 124.5 degrees Fahrenheit causing problems in the equipment
                temperature since the equipment was not created for temperatures in excess of
                105 degrees Fahrenheit, a temperature that creates a molecular breakdown of the
                components. As the optimum operating temperature is 80 degrees Fahrenheit, the
                result was an expansion of the component part beyond its maximum operating
                temperature level of 105 degrees Fahrenheit. This in turn led to a failure of
                the switch that was rectified by the engineer who assessed that the cooling
                coefficients needed with a possible ambient temperature above the manufacturer’s
                recommended levels were more in the range of 80 to 90 degrees Fahrenheit.</p>
            <p class="card-text">Three reduced settings were considered, namely reducing the
                inflow of current by 10%, 20%, or 25%. These would lead to a reduction in the
                traffic by 13%, 18%, or 32%.</p>
            <p class="card-text">The optimum setting was 25.32% of the 80,000 maximum number of
                transactions per hour rate, which was achieved by reducing the number of
                transactions, relaying the overage to other components and switches. The
                engineer then had to replace the component and reset all of the relevant
                switches.</p>

        </div>
    </div>
    <div class="card">
        <div class="card-body">
            <p class="card-title bwc-correct">Specific and concise</p>
            <p class="card-text"> Because of a sudden increase in transactions, the temperature
                in the component rose to 124.5 degrees Fahrenheit. The component’s parts
                overheated, causing the switch to fail. To keep the transactions flowing through
                the system, an engineer replaced the component, reset the switches, and diverted
                transactions to other components. That reduced the number of transactions by 25
                percent, returning the temperature to the optimum level for this component.</p>

        </div>
    </div>
</div>

<p class="example">Example</p>

<div class="card-group">
    <div class="card">
        <div class="card-body">
            <p class="card-title bwc-incorrect">Correct</p>
            <p class="card-text">Problems arose in a number of areas of the device that required
                intervention by a qualified member of staff so remedial action could be
                taken.</p>
        </div>
    </div>
</div>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla vitae dui quis eros mollis
    tincidunt ac vitae tellus. Curabitur quis sem et diam sollicitudin dignissim et sed neque. Etiam
    id diam nulla. Vivamus consequat volutpat nulla, at ornare orci pretium sed. Duis massa ex,
    facilisis at auctor eget, tempus ut nibh. Nulla lobortis nisl a lorem semper, id ultricies
    lectus vehicula. Nunc sed quam nisi. Praesent erat turpis, aliquam et massa a, tristique feugiat
    purus. Mauris egestas, elit et viverra facilisis, ipsum ipsum varius lectus, in mollis augue
    ipsum sed mi. Nullam aliquet nibh feugiat erat luctus ultricies. Sed interdum mauris non neque
    pellentesque viverra. Integer faucibus nunc ante, vel lacinia turpis tincidunt vel. Pellentesque
    maximus dictum rhoncus. Sed a mauris cursus, tempus quam posuere, placerat sapien. Fusce aliquet
    iaculis justo, vitae feugiat magna sodales id.</p>
<p class="example">Example</p>

<div class="card-group">
    <div class="card">
        <div class="card-body">
            <p class="card-title bwc-correct">Incorrect</p>
            <p class="card-text">Duis massa ex, facilisis at auctor eget, tempus ut nibh. Nulla
                lobortis nisl a lorem semper, id ultricies lectus vehicula. Nunc sed quam nisi.
                Praesent erat turpis, aliquam et massa a, tristique feugiat purus. Mauris egestas,
                elit et viverra facilisis, ipsum ipsum varius lectus, in mollis augue ipsum sed mi.
                Nullam aliquet nibh feugiat erat luctus ultricies. Sed interdum mauris non neque
                pellentesque viverra. </p>
        </div>
    </div>
</div>

Tables

Tables can be used to display lists of words, phrases, etc. Tables can also be used to compare text. As a rule of thumb, if the text is not complete sentences and/or there are more than a few examples, consider using a table.

For a table without borders, use <table class="table table-borderless"></table>

Complex, difficult words Plain English words
accelerated sped up
advise tell
along the lines of like
are of the opinion believe
                            
<div class="table-responsive">
    <table class="table table-hover">
        <thead class="thead-dark">
        <tr>
            <th>Complex, difficult words</th>
            <th>Plain English words</th>
        </tr>
        </thead>
        <tbody>
        <tr>
            <td>accelerated</td>
            <td>sped up</td>
        </tr>
        <tr>
            <td>advise</td>
            <td>tell</td>
        </tr>
        <tr>
            <td>along the lines of</td>
            <td>like</td>
        </tr>
        <tr>
            <td>are of the opinion</td>
            <td>believe</td>
        </tr>
        </tbody>
    </table>
</div>
                            

Documents

When a sample document is required, wrap the document in a div.document. This gives the div a thin outline and padding. It also adds margin below the document block. You might place a table inside the document without the borderless class if needed. See the table section.

See the examples below.

June 15, 2020
Ref: File 10384

Mr. Jeremy Frazier, President
Traymore Associates, Inc.
4834 Allison Street
Champaign, IL 61820

Dear Mr. Frazier:

Subject: Your question about our corduroy fabric

I am Linda Benson, account representative for Arnston Fabrics. We received your questions about the weave of our corduroy products. I am happy to explain the weave to you.

Our corduroy is strong and durable. It has a rounded cord, rib, or wale surface we create using cut pile yarn. The back of the fabric has either a plain or a twill weave.

                            
<div class="bwc-document">
<p>
    June 15, 2020<br/>
    Ref: File 10384
</p>
<p>
    Mr. Jeremy Frazier, President<br/>
    Traymore Associates, Inc.<br/>
    4834 Allison Street<br/>
    Champaign, IL 61820<br/>
</p>

<p>Dear Mr. Frazier:</p>

<p>Subject: Your question about our corduroy fabric</p>

<p>
    I am Linda Benson, account representative for Arnston Fabrics. We received your questions about the weave of our
    corduroy products. I am happy to explain the weave to you.
</p>

<p>
    Our corduroy is strong and durable. It has a rounded cord, rib, or wale surface we create using cut pile yarn.
    The back of the fabric has either a plain or a twill weave.
</p>
</div>
                            
                        
Top