Grammar Mechanics
It is important that we adhere to a clearly defined set of
grammatical and mechanical rules in our writing. This ensures
that we speak with in a consistent style that is tied to our brand
personality. This section lays out specific guidelines on spelling,
numbers, punctuation, and much more.
Basics
Before we get into the details, however, it is important to note
some basic guiding principles:
- Remain on message. Know your value proposition and what
you are trying to accomplish (elicit a change, empower for
success, or assure them). Tell a sequential story with a visible
structure and transition between each section.
- Be specific. Avoid vague, obscure language when possible.
Get rid of the fluff.
- Be consistent. Make sure you follow our brand style
guide and use consistent voice, grammar, and mechanics.
Inconsistency creates brand confusion.
- Be positive. Negative language is a turnoff and is in
contradistinction to Fortinet’s brand.
- Use active voice. Avoid passive voice—use active voice.
Words like “was” and “by” may be an indication you’ve slipped
into passive voice.
- Avoid slang and jargon. Write in plain English.
Tip
Looking for guidance on specific words, hyphenations, or usage? Check the glossary for a comprehensive list.
Guidelines
Unless indicated otherwise, we follow the Associated Press Stylebook (AP Style). For anything not covered in our Brand Style for Writing section, please refer to it. When rules between
the two sources differ, the ones in our Brand Style for Writing takes precedence.
Note
These guidelines are intended only for written text left to the interpretation of the reader. When providing direct guidance for the reader to perform an action in their lab environment, these guidelines should be ignored and the action should be written exactly as intended to enter. The use of code blocks and bold text help clearly delineate actions from explanatory text.
For additional help in formatting your documentation to adhere to these guidelines, check the markdown section of this document.
Abbreviations and Acronyms
Spell out the first occurrence of an abbreviation or acronym and use the short version for all subsequent references.
First Use: General Data Protection Regulation (GDPR)
Second Use: GDPR
First Use: Managed Security Services Provider (MSSP)
Second Use: MSSP
About Fortinet
Complete legal name of Fortinet is “Fortinet, Inc.” use Fortinet, Inc. when writing legal documents or contracts but use Fortinet otherwise.
Refer to Fortinet as “we” and not “it.”
Fortinet products always start with “Forti“ and end with an uppercase letter of the product (e.g., FortiNAC, FortiGate, etc.).
About Other Companies or Products
Honor their company names and do not abbreviate. Refer to a company or products as “it” and not with “they.”
Ampersands
Don’t use ampersands unless they are part of a company or brand name.
Apostrophes
Apostrophes are used for contractions (do not use them) and to make a word possessive. In the case of the latter, if the word ends in an “s” and is singular, simply add the apostrophe (not an additional “s”). If the word ends in an “s” and is plural, the apostrophe is simply added.
Bullets
Employ bullets when delineating a list that would be difficult to follow if kept within sentence structure. Do not use more than five or six bullets for a list. If it is longer than five or six bullets, then you need to break up the list into two or more taxonomies.
Capitalization
Title case capitalizes the first word of every letter except articles, prepositions, and conjunctions. Sentence capitalization capitalizes the first letter of the first word. Words that should not be capitalized in a sentence include:
- website
- email
- position titles (e.g., “Sue is the director of IT at Ford Motor
Company.”)
- college majors (e.g., “Sue majored in computer science while
in college.”)
- seasons (e.g., “Sue began working at Ford in the fall of 2012.”)
Colons
Use colons to delineate a list (not an em dash, ellipsis, or
comma).
Yes: Sue requested three solution elements: web filtering,
firewalls, and switches.
No: Sue requested three solution elements—web filtering,
firewalls, and switches.
Commas
Use serial commas when writing a list of words or putting together a list of clauses (Oxford comma).
Yes: Sue built an outstanding program that includes firewalls,
routers, and switches.
No: Sue built an outstanding program that includes firewalls,
routers and switches.
Employ a comma when breaking up complete clauses (viz., have a subject and predicate) that are joined together in one sentence.
- The Security Fabric enables customers to reduce the time spent managing manual compliance reporting, and it also provides enhanced threat intelligence.
Contractions
Our writing leans more on the side of formal than informal. Steer away from the use of contractions (e.g., “can’t,” “don’t,” “won’t,” “hasn’t,” etc.). The fact that content is translated for international audiences is another reason why we do not use contractions.
Dates
Spell out the day of the week and month (e.g., Sunday, December 23) and only abbreviate when there are space constraints (e.g., Sun., Dec. 23).
Decimals and Fractions
Spell out fractions.
Yes: one-third
No: 1/3
Use decimal points when a number cannot be expressed easily as a fraction but only to the tenths or hundredths level unless there is a valid business case.
Yes: 2.75
No: 2.7542
Ellipses
Ellipses […] are used to indicate that a thought is trailing off.
These should be used sparingly and should not be used for
emphasis or drama nor in titles or headings.
Ellipses in brackets […] are used to show the omission of words
in a quote.
Emoji
Cybersecurity is a serious business. We don’t use them.
Em Dashes and Hyphens
Use a hyphen without spaces on either side to line words into a single phrase and for compound modifiers. (Note: Compound modifiers are not separated by a hyphen when the first word ends with -ly [e.g., fully integrated solution].)
- first-ever report
- collaborative-interactive solution
Use an em dash (—) without spaces on either side to offset
asides (and do not use hyphens or en dashes [–]).
- Having a position open for a lengthy amount of time can become a real challenge for a cybersecurity organization—and a tangible pain point for a CISO.
Exclamation Points
Use them sparingly and never more than one at a time. The point of the sentence or phrase must be particularly salient to warrant an exclamation mark.
Like periods and question marks, exclamation marks go inside quotation mark. They go outside parentheses when the parenthetical is part of a larger sentence. They go inside parentheses when the parenthetical stands alone.
See Periods for examples.
File Extensions
File extension types should use all uppercase without a period. If plural, simply add an “s.”
When referring to a specific file, the file name should be all lowercase unless specified otherwise (sometimes malicious files have specific uppercase and lowercase letters; see FortiGuard.com to look up specific malicious files):
- mint.exe
- simplewallet.exe
- GandCrab.Botnet
Use endnotes unless there is a valid reason to use footnotes. The footnote/endnote number goes on the outside of the punctuation mark and not on the inside.
Yes: Ransomware attacks grew over 205% last year.
No: Ransomware attacks grew over 205% last year.
Footnotes and endnotes are only used in long-form, pillar content such as white papers, eBooks, solution briefs, etc. Hyperlinks are used in blog posts and online articles (e.g.,
TheCISOCollective.com). See the footnotes section of the markdown page for implementation details.
When there is an author’s name:
Patrick E. Spencer, “The State of the Female CISO, and What Can Be Done About It,” The CISO Collective, September 6, 2018.
When there is not an author’s name:
“Over half of consumers have decided against an online purchase due to privacy concerns,” KPMG, November 3, 2016.
When there is not a published date:
“Beneath the surface of a cyberattack,” Deloitte, accessed September 16, 2018.
When the reference comes from a referred publication published quarterly, bi-monthly, etc.:
Doug Jones, “How to Motivate Your Employees,” Harvard Business Review 91:1 (January-February 2018): 55-62.
When there are two authors:
Doug Jones and Mary Landry, “Where to Find Cybersecurity
Professionals,” SANS Institute, January 21, 2017.
When there are three or more authors:
Doug Jones, et al., “Where to Find Cybersecurity Professionals,”
SANS Institute, January 21, 2017.
Italics
For titles of books, movies, and other long works, use italics. Don’t use underline formatting or any combination of bold, italic, caps, and underline.
Money
When writing about U.S. currency, use the dollar sign. For other
currencies, the same format should be followed.
Names and Titles
Use the first and last name of a person in the first instance
where they are referenced. Use their last name in all subsequent
occurrences.
Department names are capitalized but not team when it follows.
- Security team
- IT department
Position titles are not capitalized unless they are used a titular
manner:
- Chief Information Officer Sue Hanks embarked on a search for a solution that met their business requirements.
- Sue Hanks, the chief information officer, embarked on a
search for a solution that met their business requirements.
Numbers
Numbers are spelled out when it begins a sentence. Use numerals in asset titles (research shows they generate more reader engagement). In sentences, numbers between one and nine are spelled out, while numbers 10 and above are used as numerals. Numbers with four digits or more get commas.
When numbers below nine and above 10 are used in the same context, then numerals are used.
- Numbers Nine and Below (e.g., “Sue estimated an answer between six and eight.”)
- Numbers 10 and Above (e.g., “Sue won between 50 and 90 games in three years.”)
- Mixed Numbers (e.g., “Sue discovered that attendees answered between 6 and 12 questions on the survey.”)
Do not abbreviate larger numbers in numerical form (e.g., 2K, 150K).
Periods
Periods go inside quotation mark. They go outside parentheses when the parenthetical is part of a larger sentence. They go inside parentheses when the parenthetical stands alone.
- Sue said, “Fortinet is a great solution and it has delivered tangible results for us.”
- Endpoint protection must account for users and devices (not to mention network access control).
- (Network access control is a requisite for anyone with IoT devices.)
Percentages
Use % symbol instead of spelling out “percent.”
Pronouns
If your subject’s gender is unknown or irrelevant, then use thirdperson plural pronouns (they, their, them) as singular pronouns.
Use third-person singular pronouns as appropriate (he, his, she, her). Don’t use “one” as a pronoun.
Question Marks
Question marks go inside quotation mark. They go outside parentheses when the parenthetical is part of a larger sentence. They go inside parentheses when the parenthetical stands
alone. See Periods for examples.
Quotation Marks
Use quotes to refer to words and letters, titles of short works such as articles and poems, and direct quotations. Punctuation (periods, exclamation marks, question marks, semicolons, colons, commas) go inside of quotation marks. Use single quotation marks for quotes within quotes.
- Sue said, “Fortinet is the backbone of our security strategy.”
- He noted, “Our CEO gave me a mandate, indicating that ‘we should proceed with the best solution.’”
Ranges and Spans
Use an en dash [–] to represent a range or span of numbers, dates, or time (not a hyphen). There should be no space between the en dash and the adjacent content.
Yes: Customers realize 25%–30% savings.
Yes: The webinar is scheduled for Wednesday, December 23, 11:00 a.m.–12:00 p.m.
No: Customers realize 25%-30% savings.
No: The webinar is scheduled for Wednesday, December 23, 11:00 a.m.-2:00 p.m.
Schools
Refer to a school by its full name in its first occurrence. Afterwards, you can use its more common abbreviation.
- The University of Colorado at Boulder (CU) conducted
research in cybersecurity.
- CU performs extensive research in cybersecurity.
Semicolons
Semicolons normally are used in long, complicated sentences. But be careful about overusing semicolons. Sometimes, an em dash (—) is a better option. In other instances, it may be best to break the sentence into two sentences.
Space Between Sentences
Use one space between sentences and not two.
States, Cities, Countries
Spell out all city and state names. Don’t abbreviate them. AP Style stipulates that cities must be accompanied by their state with the exception of the following:
Atlanta, Baltimore, Boston, Chicago, Cincinnati, Cleveland, Dallas, Denver, Detroit, Honolulu, Houston, Indianapolis, Las Vegas, Los Angeles, Miami, Milwaukee, Minneapolis, New Orleans, New York, Oklahoma City, Philadelphia, Phoenix, Pittsburgh, St. Louis, Salt Lake City, San Antonio, San Francisco, Seattle, Washington
Syntax Descriptions
Use code blocks for literals (parts of the language, values, and so on), italics for placeholder names, and regular text for the brackets that enclose something that’s optional. Pay close attention to punctuation.
Read ([file,] var)
Use camelcase to connect words that act as a single placeholder name (sourceFile).
Be consistent when naming placeholders; for example, don’t alternate between commands and commandList.
Time
Use numerals and a.m. or p.m. with a space in between. Use an en dash for ranges without a space between it and the adjacent words on either side. Abbreviate time zones in the U.S. For international time zones, spell them out.
Title Case
Short words with less than four letters are lowercase in titles unless they are the first or last words. However, if any of those words are verbs (is, are, was be), they are to be capitalized.
- Sue Smith, “A Short Discussion on What Is the Most Important"
- Cybersecurity Requirement,” Harvard Business Review 38:2 (2012): 65-81.
URLs and Websites
Capitalize the names of websites and web publications. Don’t italicize. Spell out URLs but leave off http://www and https://www. Or use basic links.
Content Structure
With the Fortinet-hugo theme, our content is broken down into chapters, with each chapter broken into sections. These sections are further broken down into subsections within each page.
When developing content, using the directory below can help ensure readability and consistency across all courses we create.
File Structure
content
├── 01chapter-one
│ ├── _index.md <-- /01chapter-one.html
│ ├── 01section-a.md <-- /01chapter-one/01section-a.html
│ ├── 02section-b.md <-- /01chapter-one/02section-b.html
│ └── 03section-c.md <-- /01chapter-one/03section-c.html
├── 02chapter-two
│ ├── _index.md <-- /01chapter-one.html
│ ├── 01section-a.md <-- /02chapter-two/01section-a.html
│ ├── 02section-b.md <-- /02chapter-two/02section-b.html
│ └── 03section-c.md <-- /02chapter-two/03section-c.html
├── _index.md <-- /
└── 03chapter-three.md <-- /03chapter-three.html
Content Structure
Content should be broken into chapters, and contain the following at minimum, in this order.
- Preface
- Content (Chapters, split into sections)
- (optional) Glossary
- (optional) Appendices
Preface
Every guide created should begin with a preface. The preface should provide a brief overview of the content of the guide. The preface should also contain any prerequisite knowledge the user should already have, and the learning objectives.
Learning objectives, sometimes called learning outcomes, are statements which clearly describe what is to be achieved by completion of the course. Clearly defined learning objectives also have the advantage of providing clarity to the authors, by providing the desired end state in the beginning.
Beyond the summary and learning objectives, the preface should also contain any lab logistics (e.g. register and account on qwiklabs), and if this event is being hosted in person, gives a place to provide any in-person logistics that may be useful or helpful.
Content
The chapters of content are where the author will create most of their work.
On the _index.md page of a chapter, you should include an abstract and introduction to the chapter. Optionally you may also include links to frequently referenced areas within the sections.
The sections will contain the content of the guide, and there are primarily two ways to present this information; individual learning, and classroom learning. We explore both ways of organizing your content in the style section. Remember the rule of three in learning, and try to adhere to this for maximal effectiveness.
Lastly, within each chapter, we want to include a review and troubleshooting section. This section should contain some questions that test the knowledge of the section, and include answers embedded in expand shortcode to keep the answers hidden until they’re ready to read them. These questions should test general knowledge of what was covered, as well as frequently asked questions after the guide has had some use.
Glossary
The glossary is, in fact, a type of appendix and is a list of terms found throughout the content. With the diversity of technologies covered by these guides, and the variety of experience each user may have, the glossary allows for a quick reference to common terms and phrases, and provides a location to add additional references for documentation that may help provide additional context.
The glossary included in this repo is written to be reused by other content. If there are other definitions or inclusions that should be added, please submit them.
Appendices
Any other additional information that doesn’t fit elsewhere in the document can be appended here. This could be more elaborate labs, white papers, and more.
Contributors
As the last appendix of the guide, include a contributors chapter. This chapter should contain a change log. This change log allows for quick reference to major changes and rewrites that occur, and should allow easy pinpointing of changes or losses within the git version control system. This section should also contain a notice of process to submit your own changes to the documentation as needed. If needed, this is also where license information for the written content can be included as well.
Style
There are two primary styles of content you’ll strive to develop. Those two styles are individual and classroom. Its important to choose a style when begining your development, and to remain consistent. However, these styles may be interspersed as needed. For example, an extra credit portion may cover more advanced topics not discussed in a class, which would justify pivoting to an individual style for that chapter.
- Individual
- This style is useful for computer based training (CBT), or unguided types hands-on activities. Lab instructions are interspersed with instructional information. This style is frequently used for immersion days and jam type content. It may be preceded by a quick overview of what will be covered, but is primarily individual effort, with moderators to assist individuals when they have issues.
- Classroom
- This style is to be used when presenting to a group, before then releasing them into their lab to recreate or gain hands on experience with what is discussed. When writing instructional content, the lab work should be concisely written after the content that is reviewed together.
Examples
Individual Example Chapter
- Kubernetes Overview
- Cluster Architecture
- Containers
- Nodes and Services
Note
In this example, the lesson may include the basic components of Kubernetes, followed by deploying a managed kubernetes cluster (K8s Basics). Then in the Node and Service section, Node and Service concepts would be discussed, proceeded by walking the user through looking at those concepts in their deployed environment. The lab and instructional content are interspersed.
Classroom Example Chapter
- Kubernetes Overview
- Cluster Architecture
- Containers
- Nodes and Services
- Task 1 - Launch AKS
- Task 2 - Navigating K8s by CLI
Note
In this example, the lesson is divided into 3 sections of instructional content, followed by 2 tasks to accomplish in the lab. This lends itself well to classroom environments, as presenters can review the content interactively with everyone, prior to then having the group work independently through the hands-on portion.
Chapters
A chapter displays a page meant to be used as introduction for a set of child pages. Commonly, it contains a simple title and a catch line to define content that can be found under it. Every course should contain a minimum of 3 chapters.
We create content in markdown, and place these files into the content directory. To keep these organized, we create a new directory for each chapter, and an _index.md file is created inside it. This _index.html servers as the chapter introduction. Every _index.md file should begin with the following information included at the top of the page.
Example Inclusions
---
title: "Structure, Grammar, Voice, and Tone "
chapter: True
menuTitle: "II: Structure, Voice, Tone"
weight: 20
---
- title: - is where the title of chapter is defined. This will appear on the top navigation bar, which shows users where they are in the site navigation tree. This is an important option for users on screens of narrow width (such as a tablet or phone).
- chapter: - This is a boolean value. When
chapter: true, the page is reduced to a narrower width, and is designed to be a ’title page’ for each chapter. - menuTitle: - This is an optional field, which allows the left side navigation bar to contain a different wording than the title. We try to include numbers or numerals to help with navigation, since navigation can be confusing without them, as the order is defined by
weight - weight: - Weight is used to define the order of chapters and subchapters. Lower numbers have higher priority than higher ones. Generally we use increments of 10 during initial drafting, to ensure flexibility to include additional pages later as needed. In the example above, the weight is set to 20, for the second chapter.
For organizational reasons when building chapters and subchapters, we typically will label the files and directories with numeric values collaborating eqvilant to the weight of each chapter. These are for human readability of the pre-published code only. Order within the published app is set by the weight value of each file.
Note
If a particular chapter is light on content, the directory structure can be omitted, and the markdown file can be placed directly in the content folder. It will require the value of chapter: to be set false, as chapter: true sets the theme to an introductory layout.
See the file layout section, where chapter-three.md represents this.
Sections
Sections are where the bulk of content is created. You’ve broken the content down into chapters, and used the _index.md page to prepare the summary of the chapter. Now you will build out the content in sections. Each section should contain an entire concept or lesson.
Like chapters, you should strive for a minimum of 3 sections per chapter of content. Prerequisites and appendices may not be applicable, but if you dont have at least 3 sections, consider condensing the content entirely to the chapter page, or further breaking down content into 3 sections.
Similar to _index.md pages, each subchapter should contain this information at the begining of each file
---
title: "Content Structure"
weight: 45
---
Note
See the example inclusions earlier in the chapter to understand each field. For subchapters, menuTitle and chapter: false are optional fields. We also shifted the numbering schema by 5 digits, to allow quick differentiation between chapters and subchapters.
