Editorial guidelines

This style guide provides editorial guidelines for writing technical documentation.

Overview

The intent of these guidelines is to ensure that Function Store functions have consistent quality and style. If you’d like to start contributing to our functions, you should follow these guidelines and structure when creating its documentation.

Writing style

Consider the following writing style principles before you begin documenting a function:

• Write in active voice. This puts the focus on who or what is performing the action and makes the sentence easier to understand.

• Identify the most important information and say it concisely. Don't repeat what's already been said or state the obvious.

• In most cases, address users as "you". It's friendly and engages the user directly.

• Use contractions if they make your text flow more naturally, such as "didn't" instead of "did not" and "can't" instead of "cannot."

• Show, don't tell. For example, "To use thesendSignUpWelcomeEmailfunction on a page, you can add this to your React code", then show the code block.

• Avoid shortcuts, symbols, and abbreviations that could easily be spelled out.

Format and punctuation

Bold

Use bold formatting, for UI elements and at the beginning of notes.

Capitalization

Use sentence case in all buttons, menus, and titles. In sentence case, only the first word and proper names are capped.

Italic

Use italics formatting when drawing attention to a specific word or phrase, such as when defining terms or using words as words.

Underline

Do not underline.

Lists

Add a list when you have two or more important points to reinforce or amplify. Use a bullet list when the order is not important and a numbered list for a sequence of steps to be performed in order. You can nest lists, but do not go more than three levels deep, and try to keep it to two.

The following are examples of lists:

• This is a bullet list.

  • You can use Tab to go one level deeper, and Shift+Tab to go up.

1. This is a numbered list.

   1. You can use Tab to go one level deeper, and Shift+Tab to go up.

Code

• This is inline code. Use it for referencing package names and commands.

• Key presses should be written in ALLCAPS with in-line code formatting: ENTER.

• Use a plus symbol (+) if keys need to be pressed simultaneously: CTRL+C.

• Use code blocks, <pre> or ```, for code samples or other blocks of code.

Blockquotes

Use blockquotes to display a piece of very important information.

Info: To provide some tips and extra information.

Success: To show an achievement.

Warning: To provide information that users should be aware of as there is a low to moderate level.

Danger: To provide information that is negative and has a high risk to the user.

Image

Screenshots should be in PNG format and hosted on X. Embed them in the documentation using the following format: .

Tables

Use a table to represent a set of parameters, where each parameter has a name, a data type, and a description. Don't add styling to the table element. Sort rows in a logical order, or alphabetically if there is no logical order.