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:
Provide your email address.
Complete email verification.
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
Go to https://sepal.io
Select Launch > Sign up.
Fill out the form.
Select Sign up.
Complete email verification.
Create password.
Example
To start an instance
Examine the Available instance types table to choose an instance type.
Enter your chosen instance type.
Press Enter.
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: