Voice and Tone

It's important for us to maintain a consistent voice across all of our communications, even though the tone may change from piece to piece and from writer to writer.

• We present ourselves as members of the community — peers, colleagues, comrades, friends, teachers, tutors, mentors.

• We are knowledgeable, skilled, and talented.

• We understand the needs of our community because each of us individually rose from the ranks.

• We meet our community members with compassion, empathy, and reassurance. Our collective voice is informal, friendly, encouraging, and sometimes silly. We don't take ourselves too seriously, and as the hosts of the party we're always looking for ways to make sure all of our guests are having fun.

• At the same time, we are writing for an international audience, many of whom may not have strong English language skills.

• We always prioritize the simplest and clearest way of expressing ourselves, in the interest of being understood by everyone in our community.

Grammar and Mechanics

Style and grammar can be very subjective, so it's crucial that we establish and maintain house rules for consistency across all communications.

Basics

• Write for everyone. Inclusivity is the name of the game. Don't leave anyone out.

• Use US English spelling. Our blog is international, but our company should write in US English.

Favorite, color, customize, etc.

• Be focused. Don't pad out content with unnecessary exposition. (i.e. Since the dawn of history, humanity has searched for ways to express itself. Then came the printing press. Now we have blogs. This is a blog post about something totally unrelated to all of that.)

• Be concise. Fewer words is almost always better. Still, err on the side of clarity over brevity, even if it takes more words to accomplish this.

• Be specific. Say what you mean, and state it directly. Avoid vague language.

• Be consistent. Adhere to the guidelines laid out here, and refer back to this guide when in doubt.

Guidelines

Abbreviations and acronyms

• If there’s a chance your reader won’t recognize an abbreviation or acronym, spell it out the first time you mention it. Then use the short version for all other references. If the abbreviation isn’t clearly related to the full version, specify in parentheses.

First use: Object-Oriented Programming - Second use: OOP

First use: MongoDB, Express, React, Node (MERN) - Second use: MERN

• If the abbreviation or acronym is well known, like API or HTML, use it instead (and don’t worry about spelling it out).

Active voice

• Use active voice. Avoid passive voice. In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.

Yes: Kelly published a new blog post. No: A new blog post was published by Kelly.

💡 Words like “was” and “by” may indicate that you’re writing in passive voice. Scan for these words and rework sentences where they appear.^

One exception is when you want to specifically emphasize the action over the subject.

Capitalization

• Title case prepositions and conjunctions capitalize the first letter of every word except articles. Sentence case capitalizes the first letter of the first word.

• Web3 blog headlines should be written in title case:

What Is a Fork? Crypto Forks Explained

• Subheadlines should be in sentence case:

What Is a Soft Fork?

• Don't capitalize random words in the middle of sentences. Here are some words that we never capitalize in a sentence.

website internet online email

Contractions

• They’re great! They give your writing an informal, friendly tone. Don't be afraid of them.

Emoji

• Emoji are a fun way to add humor and visual interest to your writing, but use them infrequently and deliberately.

💡 Note: the plural of 'emoji' is 'emoji.'^

• Emoji can be used anywhere in a headline - one is usually a good idea, but more than one should be very rare.

No: Hashnode to the moon 🚀! Yes: Hashnode to the moon! 🚀

Numbers

• Spell out a number when it begins a sentence. Otherwise, use the numeral. This includes ordinals.

Ten new employees started on Monday, and 12 start next week. I ate 3 donuts at Coffee Hour. Meg won 1st place in last year’s Walktober contest. We hosted a group of 8th graders who are learning to code.

• Sometimes it feels weird to use the numeral. If it's an expression that typically uses spelled-out numbers, leave them that way.

A friendly welcome email can help you make a great first impression. That is a third-party integration.

Dates

• Generally, spell out the day of the week and the month. Abbreviate only if space is an issue. Saturday, January 24 Sat., Jan. 24

Decimals and fractions Spell out fractions. Yes: two-thirds No: 2/

• Use decimal points when a number can’t be easily written out as a fraction, like 1.375 or 47.2.

Percentages

• Use the % symbol instead of spelling out "percent."

Ranges and spans

• Use a hyphen (-) to indicate a range or span of numbers.

It takes 20-30 days.

Money

• Our audience is located around the world, and so $ alone is not enough information—is it USD, CAD, AUD?

• Most of our transactions are conducted in US dollars, but this should be specified.

• When specifying USD, the $ can be omitted as it is redundant.

No: $ Yes: 20 USD

• This follows when writing about other currencies as well. We favor an abbreviation for the currency over the symbol for that currency. The abbreviation always comes after the amount.

No: EUR 50 Yes: 50 EUR

Time

• Use numerals and am or pm, with a space in between. Don’t use minutes for on-the-hour time.

7 am 7:30 pm

• Use a hyphen between times to indicate a time period.

7 am–10:30 pm

• Specify time zones when writing about an event or something else people would need to schedule.

Since Hashnode is an international company, be sure to include UTC (Coordinated Universal Time aka GMT - Greenwich Mean Time).

💡 Note: Decades never ever take an apostrophe.

No: the 80's
Yes: the 80s,

Punctuation

Apostrophes

• The apostrophe’s most common use is making a word possessive. If the word already ends in an s and it’s singular, you also add an ’s.
• If the word ends in an s and is plural, just add an apostrophe.

The donut thief ate Sam’s donut. The donut thief ate Chris’s donut. The donut thief ate the managers’ donuts.

• Apostrophes can also be used to denote that you’ve dropped some letters from a word, usually for humor or emphasis. This is fine, but do it sparingly.

Happy hackin' to all my hacker friends!

Colons

• Use a colon (rather than an ellipsis, em dash, or comma) to offset a list.

Erin ordered 3 kinds of donuts: glazed, chocolate, and pumpkin.

• You can also use a colon to join two related phrases. If a complete sentence follows the colon, capitalize the 1st word.

I was faced with a dilemma: I wanted a donut, but I’d just eaten a bagel.

Commas

• When writing a list, use the serial comma (also known as the Oxford comma).

Yes: David admires his parents, Oprah, and Justin Timberlake. No: David admires his parents, Oprah and Justin Timberlake. Otherwise, use common sense.

💡 If you’re unsure, read the sentence out loud. Where you find yourself taking a breath, use a comma.^

Dashes and hyphens

• Use a hyphen (-) without spaces on either side to link words into single phrase, or to indicate a span or range.

first-time user Monday-Friday

• Use an em dash (—) without spaces on either side to offset an aside. Use a true em dash, not hyphens (- or --).

Multivariate testing—just one of our new Pro features—can help you grow your business. Austin thought Brad was the donut thief, but he was wrong—it was Lain.

Ellipses

• Ellipses (...) can be used to indicate that you’re trailing off before the end of a thought. Use them sparingly.

• Don’t use them in titles or headers.

“Where did all those donuts go?” Christy asked. Lain said, “I don't know...”

• Ellipses, in brackets, can also be used to show that you're omitting words in a quote.

“When in the Course of human events it becomes necessary for one people to dissolve the political bands which have connected them with another and to assume among the powers of the earth, [...] a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.”

Periods

• Periods go inside quotation marks. They go outside parentheses when the parenthetical is part of a larger sentence and inside parentheses when the parenthetical stands alone.

Christy said, “I ate a donut.” I ate a donut (and I ate a bagel, too). I ate a donut and a bagel. (The donut was Sam’s.)

Leave a single space between sentences.

Question marks

• Question marks go inside quotation marks if they’re part of the quote. Like periods, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.

Exclamation points

• Use exclamation points sparingly, and never more than one at a time. They’re like high- fives: A well-timed one is great, but too many can be annoying.

• Exclamation points go inside quotation marks. Like periods and question marks, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.

💡 Never use exclamation points in failure messages or alerts.

Quotation marks

• Use quotes to refer to words and letters, titles of short works (like articles and poems), and direct quotations.

• Periods and commas go within quotation marks. Question marks within quotes follow logic—if the question mark is part of the quotation, it goes within. If you’re asking a question that ends with a quote, it goes outside the quote.

• Use single quotation marks for quotes within quotes.

Who was it that said, “A fool and his donut are easily parted”? Brad said, “A wise man once told me, ‘A fool and his donut are easily parted.’”

Semicolons

• Go easy on semicolons. They usually support long, complicated sentences that could easily be simplified. Try an em dash (—) instead, or simply start a new sentence.

Ampersands

• Don't use ampersands unless one is part of a company or brand name.

Ben and Dan Ben & Jerry’s

Ampersands are also acceptable when there are character limits in place—Twitter, for example.

People, places, and things

File extensions

• When generally referring to a file extension type, use all uppercase without a period.

GIF PDFs HTML JPG

• When referring to a specific file, the filename should be lowercase:

slowclap.gif MCBenefits.pdf ben-twitter-profile.jpg ilovedonuts.html

Pronouns

• If your subject’s gender is unknown or irrelevant, use “they,” “them,” and “their” as a singular pronouns. Use “he/him/his” and “she/her/hers” pronouns as appropriate. Don’t use “one” as a pronoun.

Quotes

• When quoting someone in a blog post or other publication, use the present tense.

“Hashnode is the best blogging platform,” says Jamie Smith.

Names and titles

• The first time you mention a person in writing, refer to them by their first and last names. On all other mentions, refer to them by their first name.

• Capitalize the names of departments and teams (but not the word "team" or "department").

Marketing team Support department

• Capitalize individual job titles when referencing to a specific role. Don't capitalize when referring to the role in general terms.

Our new Marketing Manager starts today. All the managers ate donuts.

• Don't refer to someone as a “ninja,” “rockstar,” or “guru” unless they literally are one.

Schools

• The first time you mention a school, college, or university in a piece of writing, refer to it by its full official name. On all other mentions, use its more common abbreviation.

Georgia Institute of Technology, Georgia Tech Georgia State University, GSU

States, cities, and countries

• Spell out all city and state names. Don’t abbreviate city names. Don't assume that your reader knows what state/province/country a city is located in.

• On first mention, write out United States. On subsequent mentions, US is fine. The same rule applies to any other country or federation with a common abbreviation (European Union, EU; United Kingdom, UK).

URLs and websites

• Capitalize the names of websites and web publications. Don’t italicize.
• Avoid spelling out URLs, but when you need to, leave off the http://www.