Formatting

Module content#

Formatting - Definition#

Formatting refers to how visually organized a document is arranged on the page. Formatting covers a wide range of things, including font size, font selection, lists, indentation, margins, alignment, spacing, etc. Technical documents must be reader-centered.

The information should be explained and presented in a style that is readable and easy to understand. Formatting is one of the core elements of all technical documents.

A format should show a hierarchical structure of information that guides the reader through the text.

Regarding technical writing, ensuring that the document is reader-friendly and follows a clear organizational pattern is important.

Think of it like visiting a friend’s apartment or going on vacation, where everything is in the wrong place. It can be frustrating and confusing to navigate through.

Similarly, if a technical document is not properly formatted, it can be difficult for readers to understand the content.

Certain guidelines should be followed to write a well-formatted and reader-centered technical document.

The information should be presented in a style that is easy to read and understand. Formatting is one of the core elements of all technical documents, and it should show a hierarchical structure of information that guides the reader through the text.

Common formatting elements for technical documentation:#

Headings#

Most technical articles and documents follow a particular hierarchy from introduction to conclusion. Often, the structure depends on the type of article or technical document.

Headings and subheadings are important elements of technical writing. They make your content more organized and help your readers navigate through what you have written.

Proper use of headings and subheadings increases the accessibility of your documents. One very important practice is writing descriptive and concise headings highlighting each section’s main idea

Headings are really important features in technical writing; they alert your readers about upcoming topics and subtopics and help readers skip and go to what they are interested in, in the case of long technical articles or documentation.

It can help you organize your content into large sections [major headings] and smaller sections [sub-headings]. Headings are formatted by level [first level, second level, third level], which can vary in position and formatting.

Avoid using vague headings that do not convey any specific information. Headings should clearly state what your readers should expect from your content. Additionally, keywords in your headings help you optimize your technical document or article for search engines.

Key Guidelines for Headings#

1. Always make your headings descriptive; using headings like ‘’Django plugins” does not convey the right message. Your headings should inform the reader of the content of each section.

2. Always make headings parallel in phrasing. This helps readers know if the sections are similar to the preceding ones. It is always best practice to use parallel construction to structure the phrases similarly. If one headline begins with a verb, all headlines should also begin with a verb. Example; “Conquer Your New Year’s Resolutions with These Simple Tips”

3. Ensure that your headings maintain consistency. Use type size, style, color, italics, alignment, bold, etc. These guidelines can help you design headings effectively.

4. Format headings so that they indicate their level. Always use a hierarchical format when writing headings; generally, first-level headings are larger and bolder than second and subsequent-level headings.

5. Always use a consistent style of capitalization. Headings can be capitalized using several approaches. It is important to note that the same capitalization style should be used for each heading and each subheading within the document.

Levels Of Heading#

First Level Headings#

The first level heading is the highest or main level heading. It is usually best practice for first-level headings to be the largest and should be bold.

Level Two Headings#

The second level heading is a subheading of Level 1. Second-level headings are usually smaller and different from first-level headings. When formatting, it’s usually best practice to indent the heading and align the subsequent blocks of text.

Level Three Headings#

Level 3 is the subheading of Level 2. Third-level headings are usually smaller than level-two headings. It should either be italicized or indented.

Examples of Good and Bad Heading#

Good headlines help you draw attention to your audience. Headings are a quick way to capture people’s attention and encourage them to read more.

Examples of good and bad headings to illustrate key principles.

Good Headings#

1. “Introduction to Data Analysis”

Indicates the main topic section

2. “Key Benefits of Eating Balanced Diets”

conveys the main points to be discussed

3. “Methods for improving productivity as a student”

Describes the section’s content and provides a clear focus

Bad Headings#

1. “Jewelry I found”

Vague and lacks specificity, leaving readers uncertain about the content.

2. “Chapter 1”

Generic and Uninformative: readers can’t discern the content without more context

3. “Random Stuffs”

Similar to “Random Facts”, it lacks specificity and doesn’t guide the reader

List#

In technical writing, it is important to convey information clearly and concisely. Using lists while writing can be a helpful tool in highlighting important points, properly structuring your paragraphs and sentences, and organizing your document.

Listing in technical writing can make a technical document more readable and simplified. Even with formatting a list correctly, your articles could be clearer to your readers. It is important to understand how to format a list properly.

Guidelines for Creating Lists in Technical Writing#

1. Do not split a list over two pages; try as much as possible to ensure the list stays on one page.

2. Try not to overuse lists; most importantly, a list should have complementary explanatory text to add more information about the list and its importance.

3. Ensure that the first letter of each of the list items is capitalized.

4. At least 2-8 items should be included in a list; ensure that you have at least two items in a list, or it might not be considered a list. Also, having more than 8 items in a list is too much; if the information can be merged, it will make it readable and well formatted.

5. Add spacing to the list to enhance the readability of the technical documents.

6. Always use parallel phrasing / parallel construction.

List Types#

Just as different items in a kitchen have different purposes, different kinds of lists also serve different purposes. In this section, we will look at five commonly used types of lists.

1. Bullet List                                                                                                                                  #

Bullet lists are the most commonly used type of list. They typically emphasize two or more items when a specific order is unimportant.

Bullet lists can also add whitespace to a document to improve readability. However, they are generally short and should not be used for items longer than a few words.

Examples of how bullet lists can be used:#

• To list the ingredients for a recipe
• To outline the steps in a procedure
• To summarize the key points of a presentation,
• To create a checklist of tasks

2. Numbered List#

Numbered lists should be used when the order of the listed items is important, and ideas must be expressed in chronological order.

For example, numbered lists often provide instructions, outline steps in a process, or present a sequence of events. Use of numbered lists helps convey a sense of order and progression, making it easier for readers to follow the presented information. Here is a simple, numbered list providing a clear and concise set of instructions on baking cookies

1. Gather the necessary ingredients.
2. Preheat the oven to 375 degrees Fahrenheit.
3. Combine the dry ingredients in a large bowl.
4. In a separate bowl, cream the butter and sugar together. Beat in the eggs one at a time.
5. Gradually add the dry ingredients to the wet ingredients, mixing until combined. Stir in the vanilla extract.
6. Drop rounded tablespoons onto ungreased baking sheets.
7. Bake for 10-12 minutes, or until golden brown.
8. cool on baking sheets for a few minutes before transferring to a wire rack to cool completely.

For optimal clarity, strive to keep your numbered lists within eight items. Consider dividing your list into stages or phases if it exceeds eight items.

Subsequently, review your documents and check for formatting to enhance readability.

3. In-sentence lists#

Sentence lists are typically employed when you have only two to four items and desire to preserve sentence structure and paragraphing. For instance, you could utilize a sentence list to list the ingredients for a simple recipe or the key points of a brief presentation.

Example of a sentence list:

1. The ingredients for this recipe are flour, sugar, eggs, and milk.
2. The key points of my presentation are the importance of communication, teamwork, and adaptability. As you can see, sentence lists allow you to maintain a cohesive flow while presenting a short list of items.

4. Labeled lists#

Are employed when the listed items require further explanation or elaboration. For instance, you could utilize a labeled list to define key terms or outline the steps involved in a complex process.

Nested Lists#

Nested lists are commonly used when list items have sub-lists, which are lists within a larger list. This structure can help organize and present complex information, particularly when hierarchical relationships between the items exist.

Lists are crucial features of technical writing. They enhance readability, improve clarity, and ensure that ideas are conveyed accurately and effectively.

It break down complex information into digestible chunks, making it easier for readers to grasp and retain key points. They also help to organize and structure content, creating a logical flow that guides the reader through the material.

Tables#

A table is a structured arrangement of rows and columns that presents information in a tabular format. It is often used to present selection, comparison, or study information.

Well-designed tables in technical writing can make information clear and readable and create a visual representation of results, making them more concise and organized.

Tables predominantly present numerical data, such as comparing characteristics like height and depth or listing product prices.

Tables do make it easy to compare information. It can show trends or patterns of increasing or decreasing activity.

Steps to Prepare Tables in a Technical Document#

1. Identify your audience

2. Write a clear outline

3. Create a template for your table

4. Design the Table Layout

5. Determine the Number of Columns Required

6. Select appropriate cell borders

7. Choose an appropriate font style that will be used across the documents

8. Add text elements

The following guidelines will help you to create and format tables efficiently;

Formatting Guidelines for Creating Tables#

1. Each column in a table should be properly labeled with a meaningful header.

2. A table cell should not hold more than two sentences

3. Introduce each table with a sentence that tells the readers what the list or table represents.

4. Always use parallelism within individual columns.

5. The data in the table should be properly explained so that readers don’t find it difficult to understand.

6. Tables should be simplified to the amount of data that illustrates your point.

7. A footnote proves useful for elaborating on specific aspects of one or more items in the table rather than cluttering the table with excessive information.

8. Always include enough data to illustrate your point without misrepresenting it.

An example of a table with appropriate introductory text and format

Table 1: The following table identifies States and Capitals in Nigeria and Their Slogans with Current Governor#

In summary, tables should be introduced and referenced in the text beforehand. They should be numbered sequentially and have concise, descriptive, and easy-to-understand captions.

Figures#

A figure can be considered any visual element or presentation incorporated into a technical document. Figures can encompass photographs, sketches, schematics, line graphs, and various other forms of visual representation.

In most instances, figures present data clearly and concisely. When the need arises to convey quantitative information in a visually appealing way, figures should be employed to enhance the reader’s understanding and comprehension.

Figures should be simple and clear; avoid adding borders, grid lines, background patterns, and 3-D effects.

Key Guidelines for Figures#

1. Figures should exhibit high-quality image resolution, ensuring clarity and visual appeal.

2. Each figure in a technical report should be assigned a unique identifier, enabling seamless referencing throughout the document.

Figure 3.4.2 Sales Strategy for three demo projects about to be launched

Examine Figure 3.4.2 has a unique identifier for easy reference.

3. All figure elements, including labels, captions, and legends, should incorporate a combination of letters and numbers to ensure unambiguous identification and reference throughout the technical document.

4. Figures should be simplified and explanatory, enhancing the clarity and comprehension of the presented information.

5. Avoid using overly complex or intricate figures that may obscure the intended message. Instead, opt for clear, concise, and well-organized figures that effectively convey the intended information to the reader.

6. Utilize contemporary tools to produce engaging visuals that improve technical writing. Take advantage of the features of Microsoft Office and other specialized software to design graphics that are visually attractive but also informative and efficient in communicating intricate technical ideas.

7. Add a clear, concise, and descriptive image description, and include all necessary information.

Take a close look at Figure 3.5.2 below. Do you understand what information it conveys?

Figure 3.5.2

If you take a closer look at Figure 3.5.2, you can interpret the image. However, the lack of a descriptive caption makes it difficult to be certain.

Figure 3.5.3 A Budget Bar Chart showing the percentage of T-shirt sales

Figure 3.5.3 has a numbered caption and a descriptive title. With this added information, the reader will have a clearer and more informative view of the figure.

Types of Figures#

There are many types of figures in technical writing, including but not limited to.

1. Diagrams: They are often used to represent a model or an object. These images can be manually designed or drawn using computer software. Diagrams represent objects such as buildings, vehicles, and tools.

2. Flow Chart: They are visual representations used to document and design processes or programs. It is also a pictorial representation of a process in sequential order.

3. Pie Chart: They are graphics often used to communicate varying percentages or values to each other.

4. Histogram: A histogram is a graphical representation that organizes a group of data points into user-specified ranges.

Images#

As a technical writer, you aim to craft clear, understandable, and readable documents. The goal is to provide your readers with the best possible assistance for using a product.

One excellent way to achieve this is by incorporating images into your writing. These images may include photos, screenshots, graphics, and illustrations. It improve content clarity, particularly when writing installation guides, instruction manuals, or introducing new products.

Incorporating screenshots of the process enhances clarity and comprehension when crafting technical documents, such as user manuals, how-to guides, or release notes.

When guiding a user to use a new application, it is important to ensure the instructions are clear and easy to understand. One effective way to achieve this is using images to support the text.

Outlining the steps without an image might not be as descriptive and understandable as one with an image. Images can help users visualize what they are expected to do, making it easier to follow the instructions.

Example 1#

To seamlessly utilize this app, follow these steps:

1. Navigating the Home Screen: The initial screen presents various sections allowing you to select a class based on your preferred subject.

2. Upgrading to VIP Membership: If you wish to unlock the app’s additional benefits, click the “Upgrade Now” button to become a VIP member.

3. Accessing the Finance Class: For those interested in finance, click the “Join Class” button to commence the course.

From example 1, you can see that the steps for seamlessly using the application were well-aligned and structured.

However, one thing is missing. Can you make a guess? Let’s look at the next example.

Example 2#

To seamlessly utilize this app, follow these steps:

1. Navigating the Home Screen: The initial screen presents various sections, allowing you to select a class based on your preferred subject.

2. Upgrading to VIP Membership: If you wish to unlock the app’s additional benefits, click the “Upgrade Now” button to become a VIP member.

3. Accessing the Finance Class: For those interested in finance, click the “Join Class” button to commence the course.

As you can see, the example with visuals gave a better, more readable, and more understanding explanation than the one without visuals.

So, there are several good reasons for adding visuals to technical documentation. Images make the content easier to understand, and they aid in the speed at which the information presented is processed.

It also makes complex documentation clear and concise. How and where you will use images in your documentation depends on many elements.

Indeed, images and illustrations can greatly enhance the clarity and understanding of technical documentation.

However, it is important to note that there may be restrictions on using images in certain technical documents, particularly if they contain sensitive or confidential information.

Creating professional-quality images for technical documentation often requires specialized tools and expertise that may only be available to some.

Translating illustrations can be costly, so it is important to carefully consider the need for images before incorporating them into a technical document.

General Guidelines to Consider While Adding an Image to a Technical Document#

The following guidelines are best practices for adding an image to your article.

1. The image included should be relevant to the steps you are trying to clarify.

2. Ensure you add a description and reference an image before its placement.

3. Always use appropriate and descriptive captions and labels

4. Always credit image owners and use an image containing copyrighted information

5. Always add clear images, especially while adding screenshots, either in a technical manual or release note; endeavor to use a screenshotting tool to get good screenshots.

Pictures in Documentation; “The What and What not”#

Best Practices for Adding Images to Technical Documentation

Images are an essential part of technical documentation, as they can help illustrate complex concepts or procedures and provide additional information that may not be easily conveyed through text.

Some best practices for adding images to technical documentation:

1. Choose the right image format: When selecting an image format, consider the type of image you are working with and its intended use. Common image formats in technical documentation include JPEG, PNG, and GIF. JPEGs are best for photographs, while PNGs and GIFs are better suited for screenshots or diagrams.

2. Optimize image size and resolution: Keep image sizes as small as possible without compromising quality. Large images can slow down the loading time of online documentation, while overly compressed images can affect their clarity and readability. As a general rule of thumb, aim for a resolution of 72 dpi for web-based documentation and 300 dpi for print.

3. Use descriptive image titles and alt text: Provide descriptive titles for images that accurately reflect their contents. This can help users quickly identify the image’s purpose and relevance. Additionally, provide alternative text (alt text) for each image to ensure accessibility for visually impaired users.

4. Place images near relevant text: Place them near the relevant text or instructions they illustrate to ensure that images are helpful and not confusing. This will help users understand the relationship between the image and the text and avoid confusion.

5. Label images clearly: Use labels or captions to provide additional context or information about an image. For example, if you use a screenshot to illustrate a process, label each step with a descriptive caption.

6. Use consistent formatting: To ensure consistency throughout your documentation, use the same formatting for all images. This includes size, resolution, and placement.

How to use formatting to improve the readability and clarity of your technical documentation#

Readability is simply communicating ideas in a clear and accessible way.

1. Consistency is very important in technical writing. You should use uniform styles, sizes, and formats for all elements to make your document easy to read and understand. Creating a hierarchy with fonts, colors, and alignment is also crucial in technical writing. It helps readers quickly scan the document and find the necessary information.

2. Another important thing you should consider is your audience. Always tailor your content to your readers and understand who you’re writing for. This will help you determine the appropriate language, tone, and level of technicality to use in your document.

3. Organizing your content in a hierarchical format is also essential. Creating an outline is a key tool for organization in technical writing. It helps you to organize your content and create an easier user experience for your readers.

4. Finally, simplicity is key in technical writing. Always use clear and straightforward language and write short sentences. This will help you convey your information concisely and ensure your readers can easily understand your content.

Answer the following questions.#