While we want you to maintain your own brand and style while writing, there are some facets you’ll need to adhere to in order to find success.

This guide will help you understand certain rules and guidelines you should keep in mind when writing for Novu and for the web in general.

Writing Style

👥 Audience

In most cases, we are writing articles for developers. We are centered around a “by developers, for developers approach”, so don’t be shy when it comes to the technical stuff. However, keep in mind the experience of the developer you’re writing for.

We want to be able to write for all developers, whether they’re senior engineers, CTOs, junior devs, or starting their first big project. When you plan out your article, think of who would want to recreate your project and how they would want the information given to them. Junior devs will need a little more handholding than seniors, CTOs want a bigger picture over code snippets, etc.

🗣️ Tone

The biggest thing that impacts your work is the tone of your writing. We want to aim for a conversational tone at all times, as if you’re talking to an acquaintance at a bar. This means using more “casual” wording in your writing.

Some of the best ways to accomplish a conversational tone is:

Using contractions (i.e. “don’t” over “do not”, “we’ll” over “we will”.
Talk to the reader directly with “you”.
Keep your sentences short, and varied to increase readability.
Maintain an active voice over a passive one.
Read your work aloud, and see if it sounds natural.

When you sucessfully write in a conversational tone, you’ll see a clear difference in the quality of your work — and so will your readers. While we still want to educate and inform, we can do it while still appearing personable and “real”.

🌟 Quality over Quantity

Not all posts need to be huge. It’s entirely fine to submit a piece that’s short and sweet, and it’s also fine for larger pieces. If you write a post that gets the point intended across to the reader, and you follow all these rules and guidelines, then don’t worry about how long it is.

If you happen to be working on a large project, please let us know beforehand. This helps us plan accordingly to help you either shrink it down or we can split it into two pieces.

❌ Plagiarism

Any content that is found to be plagiarizing other content online will either be rejected or require rewriting. You should not take any content as-is from any website unless you cite your sources. This includes blog post content, code snippets, and images among other components.

Word Choice

👉🏻 Use “you” as the Main Pronoun

Throughout the blog post, you should refrain from using first-person pronouns (I, we, us, etc...). You should always talk to the reader directly.

🆎 Abbreviations

When it comes to abbreviations, you should always write the full term out for the first time, and then use the abbreviation later on, like so:

“The most basic metric you can track, uptime focuses on showing you how available your API is, and helping you maintain Service Level Agreements (SLAs).”

However, the exception to this rule is when it comes to common terms within our industry, such as API, CSS, HTML, etc.

🔤 Easy English

Avoid using complicated or advanced words to make sure that all developers understand clearly the content of the blog post regardless of how fluent they are in the English language.

⌛ Talk in the Present Tense

When constructing your sentences, you should generally talk in the present tense.

For example, instead of saying, “You will start now by creating the component,” you should say, “Start by creating the component.”

💬 Use Active Voice

Try to use active voice more than passive voice. It improves the quality of your blog post.

For example, instead of “This is used by developers” say “Developers use this”.

➕ Oxford Comma

When listing 3 or more items in a sentence, use the Oxford Comma.

For example: JavaScript, CSS, and HTML.

✔️ Spell Checking

Before submitting a blog post make sure to spell-check it for any typos or grammatical errors. You can use tools like Grammarly.

📝 Terminology

“Open Source” should always be in this format (not hyphenated).
When introducing the reader to Novu, the tagline should be “open source notification infrastructure for developers”.

Blog Post Content:

Overall Structure

While we want you to maintain your own style, there are some parts that should always be present in your work, namely:

A TL;DR. These “too long, didn’t read” are an extremely basic summary of the article. In just a couple sentences, explain what the project is and what tech you’re using. It doesn’t need to be fancy, but it should tell the reader what they’re about to read.

Examples: “In this tutorial, we’ll be creating a tool that can send email notifications. To do so, we’ll use the power of the open source notification infrastructure from Novu alongside SendGrid to manage our email systems.” “We will take an organization on GitHub, review all their repositories, and check the number of merged requests done by every contributor during the month. We will declare the winner by the one with the most amount of pull requests by creating the video 🚀”

A strong, solid intro. We want to kick off our article with an intro that not only draws the attention of our reader but also informs them about the project. Our TL;DR gives a brief overview, while our intro will give us the what, why, and how. If you’re able to craft a story here, it can extend throughout the article for a bigger impact, too.
A good summary. At the end of the article, we want a nice conclusion as a sendoff. It should be brief, summarizing how our project went and why we did what we did. This should not be a generic wrap-up, it should be just as personal as the intro was.

📍Headings

You should divide each section in the blog post and add headings and subheadings when necessary. That helps the reader find the information they need quickly.

We rely mostly on Heading 2 (H2) and Heading 3 (H3) styling. Your main headers should be H2, and subsections of the main headers should be (H3).

🔠 Text Formatting

No text should ever be made bold. For section titles, only use headings. In paragraphs, bold text should be avoided. Our editing team may add in boldface, but it’s simpler for you to not worry about it at all.

📂 GitHub Repository

All of our tutorials should come with a GitHub repository of the project, working code at all. Usually, you should include this link after the introduction, and one link in your conclusion.

🖼️ Images

Rely on images to help the reader understand better the content of the article whenever possible.

If your blog post is a tutorial, make sure to include images for different steps throughout the tutorial. It assures the reader that they’re on the right track.
If your blog post talks about a certain architecture, you can provide a diagram that explains the architecture. It makes the connection between the different elements of that architecture clearer to the reader.
Avoid putting code in images. All code must be added as a code snippet.

🧑🏻‍💻 Code Snippets

As you will submit the final draft in Markdown, you should include code snippets in the format accepted by Markdown.

You can add inline code snippets by wrapping the code snippet with a single backtick (`) at the beginning and end. Use inline code snippets when mentioning variable names, functions, file paths, etc...

For example:

The product is stored in the variable `product`.

You can add block code snippets by wrapping the code snippet with three backticks at the line before and after it. You should also specify the language of the code snippet after the backticks in the line before the code snippet.