You should follow the style guide to ensure a consistent tone, formatting, and context throughout Novu’s blog.
This guide will help you understand certain rules and guidelines you should keep in mind when writing a blog post.
Blog posts have different types of audiences based on their topics and purposes. For that reason, it’s important to figure out the audience that the blog post is targeting.
A blog post that is targeting complete beginners, whether to Novu or programming in general, should have a different tone and usage of words than a blog post for those who are more advanced.
Similarly, You should write a blog post targeting developers differently than a blog post targeting business people.
🗂️ Article Type
Some article types require a certain flow to follow. If the article you’re writing falls under any of these categories then make sure to follow its guidelines:
- Platform Comparisons: Articles that compare Novu to other similar notification infrastructure platforms.
After identifying the audience of your blog post, your tone should accommodate the audience the blog post is targeting.
Technical articles targeting beginner developers, whether to Novu or programming in general, should never assume that the reader will just know how to do something or will just understand a certain concept on their own. At the same time, it shouldn’t stuff in too many details that it becomes too complicated to understand. Whenever there’s a detail that’s necessary to the topic at hand, you should explain it briefly in a simple manner.
Technical articles targeting advanced developers can skip over basic information or steps that might not be necessary to the topic at hand.
Business or general articles should avoid getting into too many technical details. It should talk about the topic in general in a way that would be understandable for non-technical people.
🌟 Quality over Quantity
Not all posts need to be long. Some are better short and sweet. 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.
Any content that is found to be a plagiarism of other content online will either be rejected or require rewriting. You should not take any content as-is from any website unless you site the referring website. This includes blog post content, code snippets, and images among other components.
You can either submit the Markdown format or submit it using tools that allow exporting the content in Markdown format. Some tools you can use are Notion and Obsidian.
👉🏻 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.
🆎 Abbreviated Terms
When you abbreviate certain terms, you should write the full term the first time you mention it, then use the abbreviation later on.
For example, Start by installing Create React App (CRA).
However, if these terms are widely known as the abbreviated version then there’s no need to mention the full term. An example of that would be HTML or CSS.
🔤 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.
✔️ 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.
- “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:
📓 Cover Image
Always base the cover image on a template from our logos and assets page . If you do not have access to this, then please contact @Sumit Saurabh (firstname.lastname@example.org) for a cover photo.
All blog posts should have an introduction section. The introduction should give a general overview of the topic at hand, then inform the reader of what they’ll learn in the blog post.
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 the Heading 2 (H2) and Heading 3 (H3) styling. 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.
📂 GitHub Repository
When the blog post is a tutorial, you should include a GitHub repository with the full working code at the beginning of the tutorial.
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...
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.
Make sure that sentences before a code block end with a semi-colon (;).
When your blog post references something from another source, you should always link to that source. That builds the post’s credibility.
Your blog post should always have a conclusion. The conclusion should wrap up what you talked about in the blog post.
Your conclusion should also mention the Discord channel. It can be something like this:
Should you have any issues or questions related to Novu, then feel free to reach out to the Novu team via Discord.