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 ``__ When addressing the audience is necessary, use the word **you** or **your**. **Example** To reset your password, go to ``__ 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: .. csv-table:: :header: "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: - `FAOSTYLE (2023) `_ - `FAO Term Portal `_ - `Names of Countries and Territories `_ For GitHub-related questions or concerns related to making contributions to SEPAL documentation, see - `SEPAL team documentation `_ - `Writing on GitHub `_ For further guidance, see: - `Microsoft Documentation `_ - `Procedures and instructions `_ - `Writing step-by-step instructions `_ - `Describing interactions with UI `_