Skip to main content

Content Style Guide

This document serves as the official guide when publishing materials by Argonaut. To ensure that documents conform to corporate image and policy, including legal requirements, and to improve consistency within and among our publication. Use this guide as the specification for all types of external-facing content, be it text or video, email or blog, tutorial, or FAQ. You get the idea.

Things to remember​

First, a quick note: ‘Audience’ in this document refers to anyone both Argonaut’s users and prospects who are reading or listening, or watching anything that Argonaut publishes.

Trust that Argonaut is for its audience—serves its audience’s goals—is useful for the audience.

This will require all our content to show (not just tell) the following:

  • Argonaut understands its audience's problems → Research & develop empathy.
  • Argonaut will empower its audience to solve their problems in the most effective way → Clear, complete, and honest information.
  • Argonaut knows what it's talking about → Expertise.

The rest of the document outlines the rules and best practices for content that will serve to build this trust. Many of these are easy to adhere to, like the grammar rules, because it's either correct or not. However, others like the best practices of Tone are subjective. In those cases, our compass will be:

“What will serve the goals of our audience the best?”

1. Grammar​

1.1 Tense​

In general, use present tense and, where appropriate, use the imperative style (’’Do this”).

We don’t say “you will do this”, rather, “you do this.” Use “will” and “shall” when you want to denote something in the future; otherwise, use the present tense. Present tense gives the writing energy.

1.2 Active voice​

Active voice is direct and demonstrates who is responsible for an action. It avoids the ambiguity inherent in passive voice. Passive voice deflects attention from who performs the specific action. For example:

Instead of - “The entire documentation was read by me.” Use - “I read the entire documentation.”

In some cases, passive voice is acceptable. For example, when you want to be vague about who is performing an action or the person responsible for an action is unknown or irrelevant.

“Mistakes were made”

“An experimental solar power plant will be built in the heart of Japan.

1.3 Simple sentences​

Use short, simple, easy-to-understand words and sentences.. You can improve many complicated sentences by splitting them into two simpler sentences, each expressing a clear idea.

Instead of - Generate realistic and timely cost estimates to minimize disruption of construction activities, because funding availability may be a limiting factor. Use - Develop realistic cost estimates and construction timelines at the start of each activity. Funds for overruns may not be available.

1.4 Pronouns​

Pronouns are used as a substitute for a noun or, sometimes, another pronoun. It should be used in either of these scenarios:

  • A pronoun may substitute for an expressed noun or pronoun, especially to avoid needless repetition. For example:

Instead of - The father told the father’s daughter that the father wanted the father’s daughter to do some chores.

Use - “The father told his daughter that he wanted her to do some chores.

  • A pronoun may also stand in the place of an already identified noun. For example, if the person addressed has been identified earlier somewhere in the sentence, the statement “John replied the teacher” can become “he replied the teacher”.

1.5 Parallel sentence construction​

Parallel construction involves the use of consistent grammatical form when offering several ideas. Every element of a parallel series must be a functional match and serve the same grammatical function in the sentence. For example:

Instead of - She did volunteer work in the community kitchen, the homeless shelter, and taught free ESL classes offered by her church.

Use - She did volunteer work in the community kitchen, the homeless shelter, and her church, where she taught free ESL classes.

1.6 Negation​

When using negatives, ensure you only use one at a time in reference to any particular idea. This prevents a double negative, which is an error in English. “I cannot find him nowhere”, is an example of a double negative.

2. Punctuation​

2.1 Spacing with punctuation​

  • Use only one space following periods, commas, semicolons, colons, exclamation points, question marks, and quotation marks. When typing on a computer, the spaces needed after these punctuation marks are proportioned automatically.
  • Use no spaces on either side of a hyphen. For example, “my mother is sixty-two years old.”

2.2 Period​

  • Always Use a period at the end of a complete sentence.
  • If the last item in the sentence is an abbreviation that ends in a period, do not follow it with another period.
  • Question marks and exclamation points replace and eliminate periods at the end of a sentence.

2.3 Commas​

  • Use commas to separate words and word groups in a simple series of three or more items.
  • When a sentence starts with a dependent clause, use a comma after it.
  • Use a comma after words that introduce a sentence, such as: well, yes, why, hello, hey, etc.
  • Use commas to enclose degrees or titles used with names. For example, Sandra Jones, M.D., **is here.
  • Use a comma to separate the day of the month from the year. No comma is necessary for just a month and year.
  • Use a comma before and after certain introductory words or terms, such as namely, that is, i.e., e.g., including, and for instance, when they are followed by a series of items.
  • Commas should come after the term etc. and enclose it if it is placed mid-sentence.

2.4 Colons​

Colons mean "that is to say" or "here's what I mean."

  • Use a colon to introduce an item or a series of items. Do not capitalize the first item after the colon (unless it's a proper noun).
  • A colon instead of a semicolon may be used between independent clauses when the second sentence explains, illustrates, paraphrases, or expands on the first sentence. For example, “He got what he worked for: he really earned that promotion.”

2.5 Semicolons​

Semicolons indicate an audible pause—slightly longer than a comma's, but short of a period's full stop.

  • Use a semicolon before such words and terms as namely, however, therefore, that is, i.e., for example, e.g., for instance, etc., when they introduce a complete sentence. For example, “I have bought the supplies; however, I was not able to buy sugar, mustard and coffee.”
  • A semicolon may be used between independent clauses joined by a connector, such as and, but, or, nor, etc.
  • Do not capitalize ordinary words after a semicolon.

2.6 Question marks​

  • Use a question mark only after a direct question.
  • A question mark replaces a period at the end of a sentence.

2.7 Parentheses​

  • Use parentheses to enclose information that clarifies or is used as an aside.
  • Periods go inside parentheses only if an entire sentence is inside the parentheses. For example, “He is with the bag (The red bag his father gave him.)”.

2.8 Bracket​

These should be used within quoted context.

  • Use brackets to explain or comment on a quotation. For example, "Four scores and seven [today we'd say eighty-seven] years ago..."

2.9 Apostrophe​

  • Use the apostrophe to show possession with a singular noun, followed by the letter s.
  • To show possession with plural nouns, simply put an apostrophe after the s. For example, Ladies’ night out.
  • Add only an apostrophe to all nouns ending in s. As in, Jones’ house.
  • Use an apostrophe with contractions. The apostrophe is placed where a letter or letters have been removed. For example, Doesn’t, it’s, can’t, you’d, should’ve.

2.10 Quotation marks​

  • Use double quotation marks to set off a direct (word-for-word) quotation.
  • Use single quotation marks for quotations within quotations.
  • Quotation marks should be used with technical terms, terms used in an unusual way, or other expressions that vary from standard usage.
  • Capitalize the first word in a complete quotation, even if it's in the middle of a sentence. For example, Jane said,” The house belongs to her.” However, do not capitalize quoted material that continues a sentence. For example, Jane said that the case was “far from over” and that “we will win”.
  • Quotation marks do not remove the necessity of using other punctuation which is required for independent reasons. punctuate your sentences appropriately, within and outside quotation marks.

3. Gender neutrality​

  • No personal pronoun in English refers to both sexes. When discussing a general category of people, instead of using he/she, rewrite the sentence in the plural to avoid gender issues. For example:

Instead of - A contestant must conduct himself with dignity at all times. Use - Contestants must conduct themselves with dignity at all times

  • Use gender-neutral nouns and pronouns, such as chair instead of chairman, and their, they, or them rather than he, she, her, or him.

4. Capitalization​

  • Capitalize the first word of a sentence and the first word after a period.
  • Capitalize proper nouns and adjectives derived from proper nouns. For example Great Britain, an American song.
  • Check out a guide on the list of items to capitalize below

Capitalization reference list

5. Spelling​

Use American, not British, spelling; consult the preferred dictionaries.

6. Numbers​

  • Spell out the numbers zero through one hundred and use figures for numbers thereafter; except for whole numbers used in combination with hundred, thousand, hundred thousand, million, billion, etc. (e.g., two hundred, twenty-eight thousand, one million).
  • Spell out all numbers beginning a sentence; with the exception of years (e.g., 2015 was a weird year).
  • Hyphenate all compound numbers from twenty-one through ninety-nine. All written out fractions too should be hyphenated (e.g., one-third of the money was lost).
  • When writing figures of four or more digits, use commas. Count three spaces to the left to place the first comma. Continue placing commas after every three digits. Do not include decimal points when doing the counting.
  • Write decimals and percentages using figures; put a zero in front of the decimal point with numbers less than one.
  • Always use the % symbol instead of spelling out “percent”.
  • Use figures for physical quantities and measurements. For example 6 meters, 3 cubic feet.

7. Formatting​

7.1 Fonts and Font size​

  • Adhere to Argonaut’s fonts of choice (Satoshi & Inter are our company fonts). Refer this.
  • In case of unavailability of the above fonts, an alternate sans serif font such as Open Sans, Verdana, Helvetica may be used.
  • When choosing font size, ensure all parts of the document are legible.
  • The title of the article or the heading of the page has to be of the H1 size.
  • Try not to skip heading size unless absolutely needed. For example, After H2, comes H3.
  • Avoid multiple H1 tags on a single page at all costs.

7.2 Page layout​

  • All texts should be in portrait orientation.
  • Landscape should be used only for figures and tables that are wider than they are high.
  • Minimum margin of 1 inch all around.
  • Use single or 0.15 line spacing, with no indentation on the first line of the paragraph.
  • Use additional line breaks between paragraphs.
  • Body texts should be left-justified.
  • Page numbers should appear at the bottom right corner.

8. Lists​

  • Always use lists to highlight, emphasize text, or enumerate sequential items.
  • Use a lead-in to introduce the list items and to indicate the meaning or purpose of the list (and punctuate it with a colon).
  • Items in all lists should have a parallel structure.
  • If the list has multiple levels, each level should contain items that are alike in function.
  • When indenting in a list, each level must have at least two items.
  • Use bullets when rank or sequence is not important. Numeric lists denote sequential items or items ranked in importance.
  • Avoid overusing lists.

9. Graphic elements​

9.1 Figures and tables​

  • keep figures and tables in close proximity to the text that describes them.
  • Always refer to the figure or table by number; not “above” or “below.”
  • Number figures and tables in sequence.
  • Tables should have meaningful row and column labels. If you use an abbreviation, explain its meaning in a footnote.

9.2 Images​

  • Give each image an informative caption and a relevant file name.
  • Always include alternate text within the \<img> tags, unless the image is solely for a decorative purpose.
  • Ensure the image(s) used do not
  • Use images only where necessary.

9.3 Illustrations​

Refer: https://developers.google.com/tech-writing/two/illustrations

10. Abbreviation and acronyms​

  • The first time you use an abbreviation or acronym in a document, spell it out. Spell out the full word followed by the abbreviation in parentheses. Thereafter, use only the abbreviation throughout the section.
  • Use periods with abbreviations that end in a lowercase letter: p. (page), vol., e.g., i.e., etc., a.k.a., a.m., p.m.

11. Clear sentences​

Refer: https://developers.google.com/tech-writing/one/clear-sentences

12. Paragraphs​

Refer: https://developers.google.com/tech-writing/one/paragraphs

13. Fit content to your audience​

Refer: https://developers.google.com/tech-writing/one/audience

14. Cohesive organization of information​

Refer:

15. Tone & Content​

15.1 Clear NOT ambiguous​

Example of ambiguous communication:

An example of ambiguous communication.

Image credit

15.2 Factual NOT presumptuous​

Example 1:

Presumptuous: Seems straightforward, right? That’s because it is!

Factual: <Omit this sentence. If it was straightforward, the reader will know. And vice-versa>

Example 2:

Presumptuous: Luckily, DummyProduct handles all of this for you.

Factual: DummyProduct handles all of this for you.

What is the problem with the above examples?

No one likes to be told how they should feel - straight-forward or not, lucky or unlucky. Let them decide for themselves.

15.3 Modest NOT complacent or arrogant​

Example:

Complacent: And, just like that, a new environment is created

Modest: That’s it. A new environment has been created, ready to be used for your applications.

15.4 Honest NOT biased​

Example:

Assume a prospect asks, “Why should I consider Argonaut?”. There are two ways to answer this question.

Biased and arrogant: Well, the reasons are obvious. We automate all the DevOps processes for you.

Honest and factual: Great question, and it’s an important one too, as this is the type of decision that shapes your team structure and determines your operations cost. Like any other type of solution, choosing to automate your DevOps comes with its pros and cons. For example… <explain the cons and the pros with the intention of empowering the reader will all the information so that they can decide what’s best for themselves>

15.5 Complete NOT partial​

Example:

Let’s say there’s an FAQ: What can't I do on DummyInternalToolMaker?

Partial answer: DummyInternalToolMaker isn't built for complicated UI interactions that are common to e-commerce or other consumer-facing websites. It works great for tools & workflows internal to your team or organization but you wouldn't get very far trying to build an attractive consumer website. For those use cases, we'd recommend you try A, B, C.

What’s wrong with the above answer?

  • It has (knowingly?) misread the intention of the reader: Most prospects who are reading this FAQ of an internal tool-maker are here because they're evaluating this tool amongst others. So they want to understand what this tool can and can’t do in the context of building internal tools.
  • It is a non-specific, non-actionable answer. All the reader knows is that they can’t do “complicated UI interactions” - but what counts as complicated and what doesn’t? The readers still do not know what they can or can’t do if they decide to use this tool.
  • It’s evasive. It never really answers the question. A copout. A sign of mediocrity. We want to either have the courage to answer the question head-on, completely or not address it at all on a public FAQ.

All the above characteristics do not serve the interest of the prospect. At best this content will be disregarded, and at worst, it will erode trust.

16. Read it out loud​

To check that your writing (whether to be published as a blog or a video) has the right flow and feel to it, read it out loud. Listen for awkward phrasing, too-long sentences, or anything else that doesn't feel natural.

Examples

To sum it up, let’s look at two examples — one good and one bad (taken from the book They Ask, You Answer) to help you understand what we mean by good content, style, and tone.

Here’s the context:

A company sells fiberglass pools. Their prospects have questions about whether they should buy fiberglass pools.

Good content:

You may be asking yourself, “Is a fiberglass pool a good fit for me?”

Great question, and it’s an important one, too, as this is the type of decision you won’t be able to go back on once it’s in the ground. Like any type of swimming pool, fiberglass comes with a set of pros and cons.

For example, because the pool shells don’t come wider than 16 feet or longer than 40 feet, there are clear size restrictions. Also, because the manufacturing process includes pre-designed “molds” to build the pool from, you can’t customize a pool’s shape, size, depth, etc beyond what you see within our available models.

But if you’re looking for a low-maintenance pool that’s smaller than 16-by-40 feet, less than 8 feet deep — and you are able to find a shape that fits your needs — fiberglass might be a great fit for you.

Bad content

You may be asking, “Why should I consider a fiberglass pool.”

Well, the reasons are obvious. They are way less maintenance, you won’t have to replaster them or replace the liner, and they go in a lot faster than any other type of swimming pool.

But if you don’t care about cleaning your pool all day long and want the added burdens that come with other types of swimming pools, fiberglass may not be the best fit for you.

Why do we consider the first one to be good and the second one to be bad?

Note they’re both grammatically correct, easy to read, and comprehensible. However, there are differences in the content, tone, and style of these two examples.

The good one objectively educates the prospect about the limitations and benefits, and then leaves it up to them to make a choice.

However, the bad one shows that the company is trying to only make a sale by talking about only the advantages, without any concern about what the right choice might be for the prospect.

So, the good one inspires trust, while the bad one will likely be disregarded by the reader thereby eroding trust in the company’s intentions.

References

This style guide represents decisions made by Argonaut regarding all external-facing communication. It supplements several standard style guides, dictionaries, and other reference material. If you can’t find something in the style guide, look in these references

Dictionary

  • Webster’s Third New International Dictionary.

Style manuals

  • The Chicago Manual of Style, 14th Edition.
  • The blue book of grammar and punctuation.

Writing guide