documentation style guide#

Help us maintain useful, clear, concise, consistent and fluid writing across the documentation by following the SEPAL documentation style guide.

Learn the basics of SEPAL documentation style and ensure that your contributions are as useful as possible for the community.

Goals and principles#

The goal of SEPAL documentation is to guide users through the SEPAL interface. As an external contributor or a member of the SEPAL team, think of yourself as a tour guide for users. To achieve this goal, the SEPAL team ensures that writing is:

useful
clear
concise
consistent
fluid

Style tips#

Here are some basic guidelines for following SEPAL documentation style.

Focus on user needs#

Consider users’ questions and goals when writing SEPAL documentation. For every article, make sure users’ questions have been addressed and answered, allowing them to achieve their goals.

Be simple and direct#

Keep language clear, concise and fluid. Use numbered and bulleted lists, instead of long paragraphs, whenever possible.

Use direct tone#

Use an active voice, the present tense, the second-person point of view, and the imperative mood.

In simpler terms: Tell the user what to do in the moment they are reading the documentation (e.g. Open the SEPAL interface and enter your email address.). Avoid addressing the audience directly, when possible. In other words, limit the use of the words “you” and “your” (e.g. To sign up for a Google account, go to accounts.google.com/servicelogin.). When addressing the audience is necessary, use the word “you” or “your” (e.g. To reset your password, go to docs.sepal.io/en/latest/setup/password.html.).

Word list#

Here is a list of common words used in SEPAL documentation.

Key terminology#

Use the following terms, when possible.

The SEPAL team#

The authors of the documentation should be referred to as “the SEPAL team” (e.g. The SEPAL team maintains the documentation to guide users through the SEPAL interface.). If the term, “the SEPAL team” has been overused, use the words “we” or “us” instead.

The SEPAL interface#

The interface should be referred to as the “SEPAL interface” (e.g. Open the SEPAL interface and enter your email address.).

SEPAL documentation#

The website where SEPAL documentation is located should be referred to as either “SEPAL documentation” or simply, “the documentation” (e.g. Learn more about SEPAL documentation by reading this article.).

A section of SEPAL documentation#

A section of the documentation should be referred to as a “section of SEPAL documentation” or a “section of the documentation”, as necessary (e.g. Discover how to register for SEPAL in the “Getting started” section of the documentation.).

An article within SEPAL documentation#

A page within the documentation should be referred to as an “article” (e.g. Learn more about the SEPAL interface in the article, “Introduction to SEPAL” in the “Getting started with SEPAL” section.).

Describing interactions with the interface#

Here is a list of common words used to describe actions in the SEPAL interface.

open
close
leave
go to
select
clear
choose
enter
sign in, sign out
switch, turn on, turn off
zoom, zoom in, zoom out

Directional terminology#

Here is a list of common words to describe location in the SEPAL interface. Indicate location in relation to objects within the interface, whenever possible.

upper left (noun), upper-left (adjective), leftmost (adjective), on the left side of
lower right (noun), lower-right (adjective), rightmost (adjectives), on the right side of
pane (instead of panel)

Other things to consider#

Here are some other basic guidelines to follow when writing SEPAL documentation.

Sentence structure#

Use an active voice, the present tense, the second-person point of view, and the imperative mood, whenever possible (e.g. Open the SEPAL interface and enter your email address.).

Capitalization#

Use sentence case (i.e. capitals only for the initial letter of the phrase and any proper names), except when mirroring appearance of text in the SEPAL interface.).

Quotation marks#

Use double quotation marks for titles of articles and sections (e.g. The “Getting started” section.). Use double quotation marks for direct quotes (e.g. for the text displayed in an error message.).

Bold#

Use bold formatting for the names of buttons, checkboxes, panes, drop-down menus, and other options (e.g. Select Export.).

Italic#

Use italicized text for introducing key terminology (only italics only at first mention) (e.g. There is formal QA/QC and informal QA/QC.).