CMC Documentation Style Guide

Explore

CMC Documentation Style Guide

Kael Espino

Recipe

Glossary

Last updated: 2022-15-08

⁠

PURPOSE: To be used as a primary reference for the CALCMENU User Guide, to standardize the external documentation format, and write quality and consistent user guides for CALCMENU products.

AUDIENCE: The EGS Technical Writer, Marketing Team, and Special Projects Team

This style guide can be further improved as necessary.

⁠

Document Formatting

Document spacing: Single-spaced

Headings and Subheadings: TBA (user-defined)

Body font: Calibri, 12pt

Numbering style (Headings and Subheadings): Multilevel list

Level 1: 1.

Level 2: 1.1.

Level 3: 1.1.1.

and so on…

Acronyms

Always spell out EGS product names:

CalcMenu Cloud > CMC

CALCMENU Web > CM Web

Always spell out acronyms when used for the first time, accompanied by its acronym enclosed in parentheses.

Never use acronyms for ideas/concepts/items that are only used/mentioned once.

Do not use acronyms in titles and headings. Instead, spell them out.

General

Write in a neutral tone in second-person point of view.

Only address the “you” in describing product features, if necessary.

Use the imperative sentence form and with the implicit “you” in numbered procedures (i.e., “Click on Add Product”, “Select two products to enable the Edit feature”).

Use “them” as the gender-neutral pronoun when addressing plural user antecedents. Do not use “he”, “her”, and “him/her”.

Sentences should be 15-30 words only, with simple tenses, and in active voice. Passive voice should be used scarcely unless it strategically helps with the smooth delivery of information.

Eliminate unnecessary words and ambiguity by avoiding adverbs and flowery language.

Avoid walls of text. Break paragraphs into short paragraphs or use lists (bullets or order) and tables whenever applicable.

Always avoid contractions.

Always write in the present tense. Never use the future tense.

Incorrect: Selecting OK will open a dialog box to confirm the transaction.

Correct: Selecting OK opens a dialog box to confirm the transaction.

Do not include features that are to be added or future improvements or future product features. Information about future versions or enhancements can be left to internal documents/product specifications.

Don't use & instead of and in headings, text, navigation, or tables of contents. However, it's OK to use & when referencing UI elements that use &, or in table headings and diagram labels where space constraints require abbreviation.

Avoid nominalizations unless it is required. Nominalizations are when verbs, adjectives, and adverbs are transformed to function as a noun. Oftentimes, nominalizations set a passage to a passive tone.

Nominalization Examples

Nominalization Examples

Type

Base Word

Nominalized

Adjective

Apply

Applicable

Verb

Refuse

Refusal

There are no rows in this table

⁠

13.

Structure

Technical documents must always follow a logical hierarchical structure. This allows the document to be scannable, enabling end-users to skim through the document with ease and precision to find what they are looking for.

Make use of meaningful headings. Headings are the primary scanning element users rely on when searching for a particular information in the document. Simultaneously, headings act as topic navigation that can be used to outline the flow of the document. Strategically place headings around relevant information from one heading to another.

Break large topics into digestible sections. For example, in documenting the process of Recipe Creation, instead of writing the entire procedure in one long single process, divide it into sections by making use of the UI and separate the Overview, Ingredients, and Procedure tab under Creating a Recipe section.

Link relevant and important information via in-document links or bookmarks. This makes the document more scannable for users looking for specific information. Simultaneously, this reduces content redundancy by pointing the reader to a specific section of the document where the information may have already been discussed such as instructions or definitions.

Units of Measurement

Units of measurement are often written in conjunction with numerical values.

1. Use numerals for measurements of weight, volume, and in count values even if the number is less than 10. Always spell out the unit unless the description is UI-specific.

100 grams 5 gallons 4 persons

2. For units in decimal form and are less than one, add a zero before the decimal point.

0.63 kilograms 0.5 liters

3. Spelled out units of measurements by default takes on its plural form except when the number is 1. Clarification: fractional numbers less than 1, which are written as decimals take on the unit of measurement’s plural form.

0.7 liters 1 kilogram .17 fluid ounces

4. Hyphenated units of measurement take on the unit’s singular form. Never hyphenate a numeral with a unit’s abbreviated form.

2-kilogram chicken breast 12-cup rice 7 lb. past

5. Only abbreviated non-SI or Imperial units contain a period at the end.

2 tbsp. of sugar 0.4 kg of chicken breast 1 gal. of milk

6. For abbreviated units (to be used when describing values as they appear in the UI), add a space between the unit and the number.

Enter a specific yield size value and select its unit. For example, “1.4 kg”.

7. If a sentence ends with an abbreviated non-SI or Imperial unit of measurement, DO NOT add another period after the abbreviation.

Enter a specific serving size value and select its unit. For example, “0.6 lb.”

1. Use numerals for measurements of weight, volume, and in count values even if the number is less than 10. Always spell out the unit unless the description is UI-specific.

Example

100 grams

5 gallons

4 persons

⁠

On writing procedures

Before writing any procedure, provide a brief description of the procedure’s goal.

Always orient the user depending on the current UI of the page being discussed.

From the Dashboard, open a recipe under the Latest Recipe pane.

On writing numbered procedures, limit the steps to 7 steps only. For longer processes that exceeds 7 steps, divide the entire process into two or more sections.

In a numbered procedure, sub-steps are labeled with lowercase letters, and sub-sub-steps get lowercase Roman numerals.

When a step has sub-steps, treat the step like an introductory sentence: put a colon or a period at the end of the step, as appropriate.

Insert screenshots between steps as needed but avoid adding a screenshot for each step unless it helps to the overall understanding of the process.

Refer to UI elements in describing the process.

Example

Example

Recommended

Not recommended

In the Name field, enter an account name.

Name the account.

To save the settings, click Save.

Save the settings

There are no rows in this table

⁠

In cases where the same sequence of actions is to be repeated under one section (i.e., same initial steps under Configuration section), use multi-action sequence to avoid unnecessary repetition of information. Do this by combining small actions with the greater-than symbol (>) in a single number.

Go to Account > Settings > Configuration tab.

Tables and Lists

Tables and lists remove the wordiness of the document. It also organizes large chunks of information into a visually presentable manner, making it easier for readers to grasp the information.

Introductory Sentences

In adding tables and lists on your document, insert an introductory sentence before the table or list occurs. This aids the reader in reading the document and contextualizes the table or list that is about to be read.

Incorrect: To do this: / Follow this process:

Correct: To change the recipe quantity, do the following:

Lists

Numbered lists

Used for ordered list of items such as procedure steps and UI descriptions that needs to be followed in order.

To copy a recipe that you created:

View the recipe that you want to copy.

On the recipe controls, select the Copy button.

This opens the Save As New Recipe dialog box where you can save the recipe to a different name.

⁠

@Recipe⁠

Once you have entered a name, select Confirm to save a copy of the recipe.

Table 6

Table 6

Column 1

Column 2

Recipe

A recipe includes all necessary ingredients, as well as the details of each ingredient from measurements to nutrients. It also comes with a detailed procedure on how to cook or prepare a recipe. In this way, CalcMenu Cloud’s Recipe page takes on a holistic approach in displaying all information related to its preparation up to the recipe’s projected cost.

There are no rows in this table

⁠

For nested sequential steps, the following numbering sequence is recommended:

Table 7

Table 7

Column 1

There are no rows in this table

⁠

For nested sequential steps with branching decisions, treat the current branching decision within the procedure as an introductory sentence before inserting the nested steps:

Unordered lists

Used for non-sequential lists such as functional scope, list of fields, and branching decisions.

Viewers can do the following:

· Copy recipes shared to the group

· View the activities tab

Tables

Table 8

Table 8

Column 1

There are no rows in this table

⁠

Tables can be used to emphasize relationships between various sets of data elements. It follows that using tables is not always necessary.

Do not use tables in the following scenarios:

· Single-unit items such as field names and procedural steps. Use a numbered or bulleted list for these data.

· Single-row items for procedures

· Paired data or two-item lists such as definitions or item descriptions

· In the middle of a sentence or a numbered list

Always use parallel sentence structures when listing each item in the list

On describing interactions with UI

In writing the procedures, use the table below as a reference for appropriate verbs in describing interactions with the CalcMenu Cloud UI.

Table 9

Table 9

Column 1

Column 2

Column 3

Verb

Use for

Examples

Click

· Buttons · Tools · Can be used strictly when referring to CalcMenu Web when interacting using a PC.

· Click the Add to Basket button. · On the top-right corner of the page, click Add Product.

Open

Recipes Module/Features Use for pages only when necessary to match the UI. Otherwise, use go to. Don't use for commands and menus.

Open a recipe by clicking on the recipe name. Open a group. Open the Product page by clicking the image.png icon on the sidebar.

Go to

Navigating from one module/feature to another. Going to particular place in the UI.

From the Dashboard, go to Settings. Go to the search bar. Go to a recipe’s Costing tab.

Select

Instructing the customer to select a specific item, including: Selecting an option, such as a button. Selecting a checkbox. Selecting a value from a list box. Selecting link text to go to a link. Selecting an item on a menu or shortcut menu.

Select one or more recipes to include in the Basket. Select a search filter among different criteria in the list. Select the product that you want to replace your current ingredient with.

Select and hold, select and hold (or right-click)

Use to describe pressing and holding an element in the UI. It's OK to use right-click with select and hold when the instruction isn't specific to touch devices.

Select and hold the drag button and move the ingredient to you desired order.

Greater-than symbol (>)

Use a greater-than symbol (>) to separate sequential steps. Only use this approach when there's a clear and obvious path through the UI and the selection method is the same for each step. For example, don't mix things that require opening, selecting, and choosing. Don't bold the greater-than symbol. Include a space before and after the symbol.

Go to Profile > Configuration > Display Layout.

Clear

Clearing the selection from a checkbox.

Clear the Brand checkbox.

Choose

Choosing an option, based on the customer's preference or desired outcome.

On the Unit dropdown, choose among the units of measurement that you want to use for the recipe yield.

Switch, turn on, turn off

Turning a toggle key or toggle switch on or off.

Switch the toggle for nutrient values that you want to show or hide in the recipe details. Turn off the toggle for the Brands that you want to hide.

Enter

Instructing the customer to type or otherwise insert a value, or to type or select a value in a combo box.

In the search box, enter… In Procedure tab, enter the recipe steps in each text area. In the Tags field, enter the recipe tags name.

There are no rows in this table

⁠

When documenting the UI, use the following prepositions.

Table 10

Table 10

Column 1

Column 2

Column 3

Preposition

UI element

Recommended

dialogs fields lists panes

In the Hidden Product dialog, click Confirm. In the Name field, enter the name of the recipe. In the Item list, select a product that you want to add. In the Ingredients pane, click the + button to increase the yield.

pages tabs toolbars

On the Product page, click Add a Product. On the Overview tab, click the Category dropdown. On the Recipe toolbar, click Print Recipe.

There are no rows in this table

⁠

[JME1]⁠

Expand this list for Word Choice, Tone, and Structure

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.