ENC 4293.0002 Technical Communication Elements » Chapter 2 Style Page Design And Visual Elements
Chapter 2 Student Writers: Jon P,
The way in which a writer expresses ideas is called writing style. Some writers, such as technical or scientific ones, have a serious, yet simple tone, while others, such as authors or poets, have an embellished or creative tone. Many writers know what it is they want to say, yet they do not know how to portray it on paper.
Writing styles are subjective, since each person has his or her own unique way of writing. The same ten people may all properly follow the rules of grammar and may all be conveying the same message, yet each person’s work is going to sound different.
Some may think that using large words and complex sentence structures are going to make them seem intelligent and that their documents are credible. This, however, should not be the author’s goal when writing the document. The most important aspect of writing the document is making certain that the audience understands its message quickly and easily. On the other hand it is important for the author not to write too informally, as if he were talking to a friend. This makes the document appear unprofessional and may even insult the intelligence of the reader.
One may be asking how the appropriate tone can be achieved. Two questions writers should ask themselves are “What is the purpose of/ why am I writing this document?” and “Who is my audience and what do I want them to understand?” The following subsections will help in answering these questions.
Think of the reasons why you are writing a document. It is vital that you understand the way in which you want to present your document, in order to give your audience an understanding of who you are and how you want the document to be read.
For example, if you are writing an angry letter to your neighbor, complaining about their dog barking in the middle of the night, then you are going to write “angrily”, in order to express your point. Likewise, if you are writing a thank you note to somebody, you are going to express kindness and gratefulness in your note.
In addition to conveying certain emotions in documents, it is important to understand who your audience is. If you are composing a resume for an employer, then your tone should be confident and should express that you are qualified to perform a job. This, as a matter of fact, applies to nearly all business-like documents. The three most important attributes to consider when conducting business writings are confidence, courteousness, and sincerity.
Likewise, an e-mail to your best friend is going to have a vastly different tone than a technical document created at work. The importance of obtaining the right tone is so that unfriendliness, informality, or unprofessionalism do not become a problem.
As mentioned in the above section, in order to present the information of the document clearly, the author must obtain a simple, yet clear tone. Using too many words can confuse, bore, or frustrate the audience. To avoid wordiness, make certain that the ideas of the document are well developed and that there is plenty of evidence to back the ideas up. Likewise, the following constructions will help with eliminating wordiness:
Ex: France bit off more than it could chew in Vietnam, and America's intervention was too little, too late.
This sentence could be improved by re-writing it as such: France obtained too much responsibility in Vietnam, and America’s intervention was insufficient.
Many people do not understand particular clichés. Take a minute to think about what you want to precisely say, and then proceed to write.
Ex: Most people usually think that many puppies are generally pretty cute.
These words are generally distracting and do not help in directing the readers’ attention to the point.
Ex: Adrienne fulfilled all our hopes and dreams when she saved the whole entire planet.
Pick only one term from each pair of terms. The message will remain the same, but the sentence will be less wordy.
Ex: The reason for the failure of the economic system of the island was the inability of Gilligan in finding adequate resources without incurring expenses at the hands of the headhunters on the other side of the island.
This sentence can be difficult for a reader to comprehend. Find each prepositional phrase in the sentence and gradually remove one after the other until your sentence is shorter, but still conveys your point. Simply ask yourself, “Who/what did what to whom/what?
Ex: The fact that I did not like the aliens affected our working relationship.
A way to improve the sentence would be to write: The aliens must be addressed professionally. Remember to always locate and then communicate the problem. Make certain that no one is represented in a negative light.
It is better to use an active voice rather than a passive voice when constructing a document, for this gives the sentences clarity and simplicity. This gives the reader ease in understanding the point since he or she can more easily locate the noun and the verb in the sentence. Watch the video below on passive and active voices then checkout some of the correct uses of the active voice compared to the passive, as well as other verb anomalies to avoid when creating a document.
Ex: The alien remains were lost by the government.(OR) The alien remains were lost.
A sentence containing a “to be” verb and a past participle is a sentence in the passive voice. Here is the above sentence revised with the active voice: The government lost the alien remains. In this case, the subject comes before the verb and the sentence does not possess a past participle.
Ex: The boy threw the ball.
In the active voice, the subject is performing or causing the action, and is therefore placed before the verb. Active voice is much clearer and simpler to understand and should be used when creating a document.
Nominalization is the instance of a verb, adjective, or adverb is being used as a noun.
Ex: The discovery of the aliens was made by the government.
An improved version of the sentence would be: The government discovered the aliens. If there are too many nouns in one sentence, the action (verb) may be disguised as one of these nouns.
Ex: The aliens have a positive effect on our ecosystem.
It is important to locate the “to be” and “have” verbs in sentences. A “strong” verb has a specific meaning and likewise carries out the precise action of the subject. Here is an improved form of the above sentence: The aliens improve our ecosystem.
Page Layout and Design
Having information well-designed and consistent in a technical document allows the readers to easily understand the context of the document. Many attributes such as document organization, referencing, accessibility, various page elements, writing styles and typography should be used when designing a technical document. It is these attributes that allow information to be structured which in return makes it easier for the reader to grasp the information being conveyed.
Document organization is something that should not be overlooked. The structure of a technical document can very slightly, but the general structure is the same. You always have your front matter, body, and end matter.
Flow and Design of Information
Below is an example for the front matter, body, and end matter. This example below list a sample for new technical writers to follow. The list is not mandatory guideline, but an example of a standard technical document layout.
|Front Matter||Body||End Matter|
|Table of contents||Theory||Index|
|List of figures||Design criteria|
|List of tables||Materials and apparatus|
|List of terms||Procedure|
The front matter is the "envelope" of your document. The elements that make up the front matter introduce the reader to the body of your document. They help the reader understand a document's who, what, why, where, and how—the author, problem, argument, organization, and method. This first part of a document is, from the reader's standpoint, the most important. It tells the reader the topic and purpose are, how your material is arranged, and where to locate items of interest. ("Mayfield Handbook of Technical & Scientific Writing")
The body can be considered the meat of your technical paper, or a better term would be the content of your document. "The body of a document consists of all material necessary for the document to fulfill its explicit and implicit goals of informing or convincing the reader, establishing trust, and documenting actions or procedures" ("Mayfield Handbook of Technical & Scientific Writing").
Last, the end matter consists of material outside the body of the document that may furnish useful references to the reader ("Mayfield Handbook of Technical & Scientific Writing").
Callouts and Referencing
Charts, pictures, tables, screen shots or similar images that supplement the body text can be found in many technical documents. Knowing how to reference these supplemental images or charts can be vital to a document’s layout and design. Referencing visual aids means designing appropriate titles for each aid and appropriate methods to reference such aids within the document’s main body of text.
Referencing Visual Aids
If used properly, images can be vital to the design of a technical document. Visual aids such as images are capable of conveying information in ways that words alone can’t. Having irrelevant visual aids can confuse the reader.
Whenever placing visual aids in a technical document it is imperative that they are placed after the body text where they are referenced. When referencing these floating blocks in your text use a constant and defined label throughout the document such as “Figure 2.3”. Where the first digit refers the current chapter and the second digit refers to the third image in that particular chapter in this case.
Figures consist of drawings, diagrams, and photographs and should be referenced as “Figures” throughout the document. These visual aids should be simple to understand and straight to the point. There should not be an abundance of figures throughout the page were as one figure would sufficient. All figures should have callouts, also known as reference numbers or title. These callouts should be located below the actual figure, but not included in the body text of the document.
Charts and tables should be referenced as “Tables” throughout the document. Tables are used to compliment text or to show a relationship that can’t be visually conveyed by text. Unlike figures, tables receive their callouts above the actual table itself.
Warnings, Cautions, Dangers, and Notes
It is important to alert readers when they could be exposed to anything potentially hazardous before they reach the time that the danger is encountered. Warnings should let the reader know of any safety measures that need to be taken before it is undertaken These Precautionary statements are vital to the readers knowledge.
Cautions tell the reader how to avoid a mistake that could damage equipment or cause the process to fail. Cautions may not be as serious to the readers as dangers, but should be more serious than warnings.
Dangers are hazardous situations. If the reader is not given proper notification dangers could result in serious injury or death. Notes provide clarification or a helpful hint on how to do a step most effectively
Guidelines for using Warnings, Cautions, and Notes
A warning should advise that if steps are not performed correctly, it could potentially endanger their safety or even their lives. Highlight warnings to make them stand out from text and present them in a box with all uppercase headings. Warnings and cautions should not be regarded as optional. They are vital for legal and safety reasons to protect lives and property. In fact, you can be sued if you fail to notify the users of your product or service of dangerous conditions that will or could result in injury or death.
It is also important to put warnings and cautions in the right place. This is located immediately before the step to which they pertain. If you insert a warning or caution statement too early, readers may forget it by the time they come to the step to which it applies. And if you put the notification too late, you almost certainly expose the reader to danger and the equipment to break down. Warnings and cautions should also be put in a distinctive format.
Warnings, dangers, and cautions should be graphically set apart from the rest of the instructions. There should be no chance that readers will overlook them. Put such statements in capital letters, boldface type, boxes, different colors (red is especially effective for warnings if your readers are native speakers of English; yellow is often used for cautions).
Be careful, though, about using colors for non-native speakers of English. Make sure your audience understands an icon or a symbol, such as a skull and crossbones, an exclamation point inside a triangle, or a traffic stoplight, often used to signal a warning, a hazard, or some other unsafe condition. Include enough explanation to help readers know what to watch out for and what precautions to take. Do not just insert the word DANGER, WARNING, or CAUTION. Explain what the dangerous condition is and how to avoid it. Do not include a danger, warning, or caution just to emphasize a point. Putting too many in your instructions will decrease the dramatic impact they should have on readers. Use them sparingly so readers will not be tempted to ignore them. Notes should only be used when the procedure calls for them and they will help readers. You can use clip art to draw readers’ attention to warning, cautions, dangers, and notes.
All images receive referencing via callouts or numbering scheme. Yet with today’s technology individuals who have physical disabilities such as blindness can still navigate computers. While it is important to address the needs of the reader, it is equally important to accommodate any physical disabilities they may have.
It’s imperative that when designing technical documents online or in a word processing program, that the document(s) are accessible to individuals with special needs.
Today’s screen screen readers can understand how to correctly read aloud electronic documents such as word files, PDFs, PowerPoints, web pages, and other electronic documents. The screen reader software reads aloud text based on the documents use of headings, captions, and body text. Screen readers are also capable of describing images or charts to the user.
When designing an electronic document placing captions and callouts only benefit individuals who are not visually impaired. Placing “alt text” into all images and tables allows for screen readers to narrate those supplemental images to the user.
Alt text or alternative text is text that describes an image or chart and is not visible within the document such as a caption would be. It is this text that is narrated to the user of the screen reader. Alt text also allows for search engines within the internet to search images adequately based on the alt text description.
Alternative Text in HTML
It is important to make online documents accessible, to set alternative text in an HTML page insert ALT or Title tags into the code. Using both the Alt and Title keywords allow the screen readers to narrate the following text. Any of the three examples listed below are acceptable.
<img src="cafeteria.jpg" height="200" width="200" alt="UAHC campers enjoy a meal in the camp cafeteria">
<table width="100" border="2" title="Henry Jacobs Camp summer 2003 schedule"> <a href="page1.html" title="HS Jacobs - a UAHC camp in Utica, MS">Henry S. Jacobs Camp</a>>
<form name="application" title="Henry Jacobs camper application" method=" " action=" ">
Alternative Text in MS Word
Unfortunately MS Office 2011 for Mac does not support alt text. However, to set alt text in MS Word 2010 for PC check out the video below. Keep in mind, when converting a MS Office document to PDF there will be no loss of Alt text settings.
Page Real Estate
With any technical document it is imperative to know the intended use of the document. If writing a report information should be abundant and fill the page adequately. If writing an instructional manual or a document with a basic outline that supplements a more in depth document, it may be more applicable to leave open white space in one of the margins so the reader to take notes or expand upon the text in their own words.
Most technical documents will utilize one column throughout the document, however there will be times when multiple columns may be used for a section of the document to fill-in an excess of open space. Notice how the document on the left in Figure 1.3 utilizes a single column throughout the entire document. This allows for a fair amount of open space in the top right hand corner of the document. To overcome this, the document on the right splits the bulleted list into two separate columns while leaving the main body of text as a single column.
Rivers of White
While most technical documents will align text with the left margin, writing styles in newspapers and magazines will often justify text. When text is justified, the text aligns evenly with both the left and right margins of the document. As a result, the spacing in between each word can vary in length. This spacing is known as “Rivers of White Space” which can easily be seen in the image to the right.
Should the need to use justified text comes about, the best way to limit rivers of white space is to decrease the size of the font. Other methods include increasing or decreasing the leading and adjusting the length of the margins. One of the biggest obstacles to overcome when using justified text is to remain consistent with the text formatting while limiting the appearance of white space in the body of text.
When creating a technical document it is imperative that a general page design is well thought out. Good page design consists of headers and footers, correct justifications, utilizing the graphics properly, typography, and spacing. Without these attributes documents would be “bland” and information may not be easily understood.
Headers and Footers
Headers are placed at the top of each page in the document and allow the reader to distinguish basic information about the document or current sections of the document. Depending on the nature of your document, the header may contain the document’s title, current chapter, your name, course titles, or a business/department’s name. Headers can have various designs and font justifications. Refer to Table 1-1 for information regarding the various technical documents the information their header may contain.
|Type of Document||Content Of Header|
|General Report||Title of report|
|Memo||Personal/business contact Information|
|School Report||Course and students name|
|News Letter||Publishing Co. and date|
|Website||Name of website, logo, and name of current page|
In all technical documents footers are located on the bottom of the page. The footer contains a number indicating the current page. With online technical documents in HTML information is not sorted into pages, but rather hyperlinks, it’s because of this that the footer is located on the bottom of each individual web page throughout the site.
Notice in Figure 1.2 online footers may contain one or more of the following, copyright dates and information, business/department name, links to career opportunity, about page, terms of conditions, privacy statement, trademarks information, contact information, and help/FAQ information.
Another way to ensure a document can easily be read is by allowing content to be well-spaced. Information about a specific topic should be spaced further away from a different topic. Similar topics should be spaced closely together, while different topics should receive new headings and be placed relatively far apart. Likewise, headings give the reader a sense of guidance and ease while attempting to elaborate on a single subject.
It is additionally important for the document to have white space, in order to give the document a better appearance and readability. White space is merely an area in a document that contains no text or images, such as the space between this paragraph and the above one. Like spacing, indentations give the document more white space and also help to distinguish between paragraphs.
Likewise, it is vital that there need not be too many subsections on one section. For example, if one subsection has only one to two sentences in it, it could probably be combined with another subsection or put in the introduction. Spacing should always be used between titles, sections, subsections, graphics, lists, tables, and the like.
Though information can be organized by paragraph or section, it is also helpful to use either number or bullet lists. When information is organized into a list, it is often much easier to recall. Lists should only be made, however, if a particular point is being emphasized, or if a chapter or section is being summarized. One should not try to incorporate complex or lots of information into a list. In addition, number lists should be used if data needs to be put into a sequential order. Bullet lists, however, can be used if the order of the lists’ items is not important.
When data, a process, or a description of something is difficult to explain or a reader needs to visualize a concept, then charts, tables, pictures, graphs, and figures are helpful. Likewise, they immediately attract the reader’s attention to the information. It is additionally important that the author does not put too many visuals on one page, for it may make the page look too overwhelming or busy. All in all, a document must have a balance between visual content and written content.
Typography is simply the art of arranging type, type design, and text on a page. It is an important aspect in creating any technical document. Though many people think that the content itself is more important than the appearance of the document, they do not understand that typography attracts the reader’s attention to the document in the first place. Check out the brief introduction video to typography below.
Serif vs. Sans Serif Fonts
It is important for the document to be attractive, but its typography must also match the style and tone of the document’s content. One must be careful not to use too many font enhancements, colors, or font types. This will only distract the reader and may change the message of the content.
It is vital to know which type of font is more beneficial to use. Serif fonts are more easily read than sans serif fonts because the letters are more sharply defined. Likewise, variable-width fonts have the same effect. Because their letters are placed closely together, they appear more cohesive, as opposed to fixed-width fonts, whose letters that are spaced apart equally, appearing more awkward. The following picture illustrates the difference between serif and sans serif fonts.
Serif fonts are more likely to be used when composing a more professional, technical, or formal document while sans serif fonts are more likely used in memos, e-mails, or informal documents.
It is also important that the reader feels comfortable and informed when reader a particular text. Twelve point type font is approximately the preferred font size, for anything larger than 14 seems loud or aggressive, and anything smaller than 10 appears secretive. In addition to proper font size, the style attribute of a text, such as bold, italic, or underline, allows an idea to be more effectively communicated. Style attributes can create emphasis or point the reader to an important point within the text.
The above mentioned style attributes, bold, italic, and underline, are used to emphasis specific words, titles, or phrases in a document and each of them serves a different purpose.
Of the three style attributes, bold face stands out the most. It is used to bring immediate attention to important parts of a text and for easy scanning of a document. It is easy for the reader to locate information in bold face type.
Typically, one does not use italics to initially draw the reader’s attention. The purpose of italics is to emphasis a certain word or phrase as the reader is reading the text. Phrases in different contexts, such as foreign languages, metaphors, similes, and book titles are in italic type face.
Underlining is not typically used in technical documents, but it does not mean it is unimportant. The main function of underlining is to show grammatical errors, such as in Microsoft Word and editing. Likewise, it is used when citing sources in a document.
When using visual aids in a technical document it's important to consider their function. Visual aids are used to draw attention to information while assisting in emphasizing a point to the reader. Technical writing and graphics generally go hand-in-hand. Visual aids are used to break up text, add interest, and present data. That being said, it's important to use visual aids appropriately. Experience has shown that readers who are bombarded with excessive graphics can easily get lost in the document off and begin to glaze over the document. Losing the readers interest will hurt the reader’s ability to receive the documents full message. It's a good rule of thumb to stick with the 80-20 ratio while writing a technical document. This means 80% text with 20% graphics.
Such visual aids need to standout from the text. This can be accomplished by using boxes, boldface, headings, expressive font style, font size, or contrasting font colors. By using tables, charts, maps, or other visual aids, the reader is able to more readily identify relationships inside of the text.
Using Appropriate Visual Aids
Graphics can complement your technical document, but pictures are only useful if appropriately used. Visual aids are only of value if used sparingly and within the context of your words. Let's take a look at three simple guidelines technical writers should use when implementing graphics into their document.
First, make sure to keep it simple. The Best visual aids are those that are straight to the point. These graphics are simple in nature, allowing the reader to focus on the text more.
An intricate photo full of complex images is going to be a distraction because your reader or audience is likely to get
more caught up in the detail and lose track of the message.
The key is to use the graphic as a way to complement your
words, not replace or detract from the message. In business communications, less is more when it comes to using images. (Goessl)
Second, use visual aids sparingly. This goes along with keeping it simple, but instead of using a simple picture it refers to keeping the page simple by not over filling the page with excessive graphic. Remember the rule of 80-20, this goes right along with that. While graphics can enhance your document, they can also turn readers off if the page is filled with too many pictures. Understand that visual aids are just that, visuals that aid the text.
Third, use attractive visual aids. The common reader doesn't need any distractions while reading your document so make sure that all visuals used are clear and crisp. Graphics that are fuzzy or faded only become a distraction. This takes all the focus off of the text while the readers are trying to decipher the unclear picture. Rule of thumb is to select appropriate and high quality photos.
Proper Uses for Graphics
People read from the top and left sides of the page. This is also known as “cascading” or “Z” patterns. These results mean that the most important information should be shown in the top-left part of the screen. In electronic documents many times you only have milliseconds to draw a reader in. This means that it is important to make an impression on the readers by using the right balance between information and visual presentation. Using the aforementioned tactics should make it easier to attract the target audience and entice them to stay.
Just a few examples for how graphics can be used are to help sell something that people need to see before buying, catch a reader’s attention, or help diagram complicated instructions. It is very important to use various tables, charts, drawings, and other informational graphics in order to inform the reader in the most beneficial manner. When used in a technical document it is valuable to know when and where to place graphics. It is just as valuable to know when and where not to use graphics.
• Use graphics that are informative to the subject matter presented in the document
• Supplement any images with text describing what the image is representing
• Make an impression (positive or negative depending on subject) to draw the reader’s attention.
• Use images that are directed toward the target audience
Things to avoid
• Don’t use graphics that resemble ads, people have learned to gloss over these
• Don’t use graphics that are unrelated to the site or topic, or use images that are hard to understand
• Don’t use too many images on the same page. Websites with too many images take a lot longer time to download and this discourages viewers to stay and read the material.
• Don’t use extremely large images that will not fit onto a viewer’s screen. This not only makes it difficult to read, but also takes a long time to download.
Types of Visual Aids
There are various types of digital graphics that are used in mobile and web development. The main file types include:
• TIF – Only the lossless LZW compression allowed, useful for small files
• JPEG – normally used for rectangular photos. “Uses ‘lossy’ compression, but its degree is selectable, for higher quality and larger files, or lower quality and smaller files.” ‘Lossy’ compression is a compression method that reduces the size of a file with varying or adjustable loss of data.
• PNG – “uses ZIP compression which is lossless, and slightly more effective than LZW (slightly smaller files). PNG is a newer format, designed to be both versatile and royalty free, back when the LZW patent was disputed.” LZW stands for Lempel-Ziv-Welch is a universal lossless data compression algorithm created by Abraham Lempel, Jacob Ziv, and Terry Welch.
• GIF – “uses lossless LZW compression, effective on indexed color. GIF files contain no dpi information for printing purposes”
Table 1 – Best and Worst Uses For Graphic File Types
Photographic Images Graphics, including
Logos or Line art
Properties Photos are continuous tones, 24 bit color or 8 bit Gray, no text, few lines and edges Graphics are often solid colors, up to 256 colors, with text or lines and sharp edges
Best Quality TIF or PNG (lossless compression
and no JPG artifacts) PNG or TIF (lossless compression,
and no JPG artifacts)
Smallest File Size JPG with a higher Quality factor can be decent. TIF LZW or GIF or PNG (graphics/logos without gradients normally permit indexed color of 2 to 16 colors for smallest file size)
(PC, Mac, Unix) TIF or JPG TIF or GIF
Worst Choice 256 color GIF is very limited color, and is a larger file than 24 bit JPG JPG compression adds artifacts, smears text and lines and edges