SEPALSTYLE#

Learn the basics of SEPALSTYLE – the SEPAL documentation style guide – to keep writing useful, clear, concise, consistent and fluid

Goals and principles#

The goal of SEPAL documentation is to guide users through the SEPAL interface and help users achieve their goals.

When contributing to SEPAL documentation, think of yourself as a tour guide for SEPAL users.

To help users achieve their goals, writing should be:

  • useful

  • clear

  • concise

  • consistent

  • fluid

Style tips#

Basic guidelines for following SEPALSTYLE include:

  • focus on user needs

  • be simple and direct

  • use a direct tone

Focus on user needs#

Consider user goals and questions when contributing to SEPAL documentation. Define these goals and identify these questions before, during and after making contributions, so that articles can be useful and clear for users.

Ensure user goals are kept in mind when planning, drafting, and finalizing content. Ensure user questions are addressed and answered in the documentation, minimizing confusion and allowing users to achieve their goals.

Be simple and direct#

Keep language clear, concise, consistent and fluid. Prefer bulleted and numbered lists to sentences and paragraphs. When sentences or paragraphs are necessary, prefer short sentences and paragraphs to long sentences and paragraphs. Use section headings to organize articles.

Example

Reset password

If you have forgotten your password and you have access to the email address associated with your SEPAL account, you can reset it by submitting a request. Simply follow the instructions located on one of the website’s sign in forms.

The password reset process can be performed in three steps:

  1. Provide your email address.

  2. Complete email verification.

  3. Create a new password.

For simple step-by-step instructions, use right angle brackets.

Example

Select Launch > Sign up.

For step-by-step instructions for complex procedures, use numbered and bulleted lists, instead of paragraphs, when possible.

Example

To create an account

  1. Go to https://sepal.io

  2. Select Launch > Sign up.

  3. Fill out the form.

  4. Select Sign up.

  5. Complete email verification.

  6. Create password.

Example

To start an instance

  1. Examine the Available instance types table to choose an instance type.

  2. Enter your chosen instance type.

  3. Press Enter.

  4. Wait for the instance to start.

Use a direct tone#

When writing an article, use:

  • an active voice

  • the present tense

  • the second-person point of view

  • the imperative mood

In other words, tell the user what to do in the moment they are reading the documentation.

Example

Open the SEPAL interface and enter your email address.

Avoid addressing the audience directly, when possible (i.e. limit the use of the words you and your).

Example

To sign up for a Google account, go to https://accounts.google.com/servicelogin

When addressing the audience is necessary, use the word you or your.

Example

To reset your password, go to https://docs.sepal.io/en/latest/setup/password.html

Key terminology#

Common terms used in SEPAL documentation include:

  • the SEPAL team

  • the SEPAL interface

  • SEPAL documentation

  • a section of SEPAL documentation

  • an article within SEPAL documentation

  • a subsection of an article within SEPAL documentation

The SEPAL team#

The authors of the documentation should be referred to as the SEPAL team.

Example

The SEPAL team maintains the documentation to guide users through the SEPAL interface.

If the term, the SEPAL team, has been overused, use the authors of the documentation, or we or us instead.

Contributors to SEPAL documentation can be used for external contributors to the documentation.

The SEPAL interface#

The interface should be referred to as the SEPAL interface.

Example

Open the SEPAL interface and enter your email address.

Elements of the interface should be formatted in bold and sentence case.

Example

Select the Area of interest button.

The SEPAL documentation#

The website where SEPAL documentation is located should be referred to as either SEPAL documentation or simply, the documentation.

Example

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. The titles of sections should appear in sentence case.

Example

Discover how to register for SEPAL in the section, Getting started.

An article within SEPAL documentation#

A page within the documentation should be referred to as an article. The titles of articles should appear in sentence case.

Example

Learn more about the SEPAL interface in the article, Introduction to SEPAL.

A subsection of an article within SEPAL documentation#

A subsection within an article of the documentation should be referred to as a subsection of an article. When referring to subsections, their titles should appear in sentence case.

Example

For more information, see the Set up your GEE account subsection of this article.

Note: When formatting titles of subsections, the appropriate symbols should be used (i.e. from Heading 1 to Heading 6: =, -, ^, “, #, +). For further guidance, see the Guidelines subsection of the Contribute article.

Describing interactions with the SEPAL interface#

Actions#

Common words used to describe actions in the SEPAL interface include:

  • choose

  • clear

  • click (prefer select, except when not appropriate)

  • click and hold

  • close

  • copy

  • copy and paste

  • double-click

  • enter

  • fill out

  • go to

  • hover

  • leave

  • log in, log out

  • open

  • monitor

  • pan

  • press

  • register

  • save

  • select (use instead of click, except when not appropriate)

  • select and hold

  • sign in, sign out

  • sign up

  • submit

  • swipe

  • switch

  • turn on, turn off

  • use

  • view

  • zoom, zoom in, zoom out

Elements#

Common words used to describe elements in the SEPAL interface include:

  • app

  • band

  • bar

  • button

  • checkbox

  • dash

  • dashboard

  • dialog

  • dock

  • drawer

  • dropdown menu

  • feature

  • field

  • files

  • filter

  • folder

  • form

  • icon

  • interface

  • map

  • menu

  • module

  • option

  • pane

  • parameter

  • pointer

  • pop-up menu

  • pop-up window

  • recipe

  • settings

  • status bar

  • tab

  • terminal

  • tile

  • tutorial

  • window

  • workflow

Elements and actions#

Common words used to describe elements and actions in the SEPAL interface include:

Element

Action

Example

app

select, open

Select the Apps icon.

band

select, choose, apply

Select the Break analysis band.

bar

go to, view, select, monitor

View the Status bar to monitor the download progress.

button

select

Select the Terminal button.

checkbox

select

Select the Display map checkbox.

dashboard

go to

Go to the Apps dashboard.

dialog

view, select

Select Confirm in the dialog.

dock

select

Select the Files tab in the dock.

drawer

open, close

Open the Navigation drawer.

dropdown menu

open, select, choose

Select Vector file from the dropdown menu.

field

enter

Enter your credentials into the Username and Password fields.

files

go to, search, navigate through, save to

Select the Files icon to open your SEPAL folders.

filter

apply, turn on, turn off

Apply the Cloud detection filter.

folder

open, save to

Save to your SEPAL folders.

form

fill out, submit

Fill out the Reset password form.

icon

select

Select the Apps icon.

interface

log in, log out

Log in to the SEPAL interface.

map

click, click and hold, hover, zoom in, zoom out, pan

Click on the map to select a point.

menu

open, close

Open the Recipe menu.

option

choose, select, use

Select the Daily imagery option.

pane

go to, view

View the Recipe pane.

parameter

select

Select the Exportation parameters.

pointer

use, click, click and hold, hover, move

Move the pointer to the map.

pop-up menu

view, select, choose, close

Select the checkboxes in the pop-up menu.

pop-up window

view, select, choose, close

View your options in the User report pop-up window.

recipe

open, go to, select, save, export, edit

Select the Time series recipe.

settings

open, go to, select, turn on, turn off

Open Settings.

status bar

view, monitor

Monitor the download progress in the Status bar.

tab

select, view

Select the Process tab in the dock on the left side of the screen.

terminal

open, go to, select

Go to the SEPAL terminal.

tile

open, go to, select, view

View the Visualization tile.

window

open, close, view, select

Open your browser window.

Directional terminology#

Common words to describe location in the SEPAL interface (indicate location in relation to objects within the interface, if possible):

  • upper left (noun), upper-left (adjective), leftmost (adjective), on the left side of

  • lower right (noun), lower-right (adjective), rightmost (adjective), on the right side of

  • beside, next to

  • corner

Other things to consider#

Other basic guidelines to follow when writing SEPAL documentation include:

  • prefer sentence case over lowercase or all caps;

  • use bold for elements of the SEPAL interface, or emphasis (sparingly);

  • use italics for introducing new terminology, or emphasis (sparingly);

  • use punctuation to improve clarity and fluidity;

  • introduce acronyms at first use;

  • present highlighted information strategically and accurately;

  • format file names with lowercase letters and a full stop;

  • format numbers with neither spaces nor punctuation, except for a full stop for decimals;

  • use the author–date system for referencing;

  • introduce lists with an opening phrase ending with a colon, and use consistent capitalization and punctuation; and

  • use the International System of Units (SI).

Abbreviations#

At first mention, acronyms should be written out, followed by the abbreviation in parentheses. It may then be used alone.

Example

The project is from the Food and Agriculture Organization of the United Nations (FAO).

Exceptions can be made where justifiable (e.g. when an acronym appears in a name and the written-out version is long). In these instances, introduce the acronym in a way that is reader-friendly.

Abbreviations such as e.g., i.e. and etc. should be avoided; however, when necessary, use them in parentheses (e.g. means “for example”; i.e. means “that is”).

Example

Harnessing cloud-based supercomputers and modern geospatial data infrastructures (e.g. GEE), the interface enables access and processing of historical satellite data as well as newer data from Landsat and higher-resolution data from Europe’s Copernicus programme.

Font#

Bold#

Use bold formatting for the names of elements in the SEPAL interface, or emphasis.

Example

Select Export.

Capitalization#

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

Example

Area of interest selection

The area of interest (AOI) is the first mandatory input in the majority of SEPAL modules.

Italics#

Use italicized text for introducing key terminology at first mention, or emphasis.

Example

There is formal QA/QC and informal QA/QC. Formal QA/QC refers to …, while informal QA/QC refers to …

Punctuation#

Colons#

Use colons to introduce lists, definitions, explanations or quotations.

Example

In this section of SEPAL documentation, you can learn how to:

  • register to SEPAL

  • use GEE with SEPAL

  • use NICFI–Planet Lab data

  • exchange files with SEPAL

  • manage your resources

  • reset your password

Commas#

A comma may separate two independent clauses before a conjunction, set off complementary information, be used before the final “and” in a list to avoid ambiguity, or be used where a sentence comprises a complex series of phrases.

Example

By default, SEPAL is in English, but is also available in other languages, such as French and Spanish.

En-dashes#

En-dashes (–) are longer than hyphens (-). They can be used in pairs – leaving a space on either side – to set off an element that is not part of the main sentence. Ideally, they should not be used more than once per paragraph. An en-dash can be used alone to add a phrase elaborating what has gone before – leaving a space on either side. En-dashes are used for relationships, ranges of values and ranges of dates.

Example

2016–2020

Full stops#

Use full stops at the end of sentences, but not in headings.

Example

Set up your accounts and request additional resources

In this article, you can learn how to create a SEPAL account.

Hyphens#

Hyphens can be used: for compound adjectives, when describing ages, amounts or lengths of time, separating a prefix from a date, etc.

Example

High-quality data for 15 year-old forests.

Parentheses and brackets#

Parentheses are used to include less important text in a sentence or to enclose descriptive information.

When only part of a sentence is enclosed in parentheses, punctuation is placed outside.

Example

Open the Optical mosaics recipe (for more information, see figure below and https://docs.sepal.io/en/latest/cookbook/optical_mosaic.html).

When a complete sentence is enclosed in parentheses, its punctuation is also enclosed.

Example

(You should see an interface like in the following figure.)

Quotation marks#

Use double quotation marks for direct quotes (e.g. for the text displayed in an error message).

Example

If the following error message is displayed, continue to Step 2: “Can’t open file. No such file or directory.”

Semicolons#

Use semicolons to separate independent clauses that have different subjects and are not connected by a conjunction; in long sentences comprising a series of complex clauses, at least one of which contains a comma, semicolons may replace commas.

Example

These overlay areas can be managed in various ways. For example, you can choose to:

  • keep only the raster data from the first or last dataset;

  • combine the values of the overlay cells using a weighting algorithm;

  • average the values of the overlay cells; or

  • take the maximum or minimum value.

File names#

Format file names with a full stop and lowercase file type.

Example

.tiff

Highlights#

Common terms for showcasing information include:

  • Attention: To be used to showcase extremely important information.

  • Important: To be used to showcase moderately important information.

  • Note: To be used to showcase important information.

  • Tip: To be used to showcase helpful information.

Avoid “Warning” and “Danger”.

Numbers#

To avoid confusion, format numbers with neither spaces nor punctuation, except for a full stop for decimals.

Example

10000 hectares

Example

0.175 m

Generally, numbers from one to ten are written in text as words; numbers from 11 upward are written as numerals. Use arabic numerals for dates, percentages, money, measurements, ages, ratios and scales. Write out any number that begins a sentence. Use numerals where a number accompanies a unit.

Paragraph#

Lists#

When presenting bulleted and numbered lists, introduce them with an opening phrase ending with a colon.

For very short entries, the list items are lowercase with no punctuation.

Example

Select one of the following categories:

  • background

  • foreground

  • special background 1

For longer entries, the list items are lower case and end with a semi-colon; the final entry should end with a semicolon and the word “and”.

Example

A variety of audiovisual equipment is available to staff members, including:

  • radios, for communicating between locations;

  • televisions, for screening content; and

  • cameras, for recording events.

For entries that are complete sentences, the list items are sentence case and end with a full stop.

Example

Keep the following in mind:

  • The transition of land cover over time provides important insights into how land characteristics have changed.

  • Trends in land productivity measure important changes in productivity over time.

  • Changes in above ground and below ground carbon stocks are currently shown by soil organic carbon (SOC) stocks.

Referencing#

When referencing source material, use the author–date system, which includes in-text citations and a reference list with all sources at the end of the article. Use FAOSTYLE and Zotero to format reference list entries.

Example

In 2008, GuidosToolbox was developed as a graphical user interface (GUI) to Morphological Spatial Pattern Analysis (MSPA) of raster data (Soille and Vogt, 2009).

Example

References

Soille, P. and Vogt, P. 2009. Morphological segmentation of binary patterns. Pattern Recognition Letters, 30(4): 456–459. https://doi.org/10.1016/j.patrec.2008.10.015

Units#

Use the International System of Units. Do not use punctuation or letter spacing; however, always insert a space between the unit and the number. If using symbols, introduce at first use in parentheses.

Example

Information is gathered every 5 metres (m). Every 50 m, a report is generated.

A note on SEPALSTYLE#

SEPALSTYLE was developed during copy-editing to improve the presentation of information in the documentation and enhance user experience.

This style guide can be considered exemplary documentation (i.e. a model text for writing articles and presenting information).

For style-related questions or concerns not addressed in SEPALSTYLE, see:

For GitHub-related questions or concerns related to making contributions to SEPAL documentation, see

For further guidance, see: