Writing your first community tutorial

This space is dedicated to Earth Engine users who want to share their knowledge with the rest of the Earth Engine community. Created by Earth Engine users, for Earth Engine users, tutorials in this section are intended for all levels, from beginner to more advanced users.

Tutorials may be submitted as plain text and code formatted using the Markdown markup language, or as Colab notebooks containing Markdown and executable Python code. Tutorials built using the Earth Engine JavaScript client libraries are generally written in Markdown, while Colab is recommended for tutorials based on the Earth Engine Python client libraries.

Before you begin

Code of Conduct

The Earth Engine team is committed to fostering a harassment-free and inclusive community. Please familiarize yourself with our Code of Conduct before contributing.

Joining GitHub

Earth Engine community tutorials are shared and reviewed through GitHub. If you don't already have a GitHub account, you must first create one at https://github.com/join.

Proposing a tutorial

Before investing significant time and effort on a new tutorial, potential contributors are asked to submit a simple proposal with some basic information. This allows authors to work with the maintainers of the Earth Engine developer documentation to focus efforts on tutorials that provide the most value to the Earth Engine user community. It also saves time by avoiding potential back-and- forth during the review process.

Propose a tutorial

First time setup

If this is the first time you're submitting a tutorial to the Earth Engine community GitHub repository, be sure to complete these steps before starting work on your tutorial:

  1. Accept the Contributor License Agreement (CLA) at:

    https://cla.developers.google.com

  2. Read and internalize the Community Tutorial Style Guide.

Writing and submitting a tutorial

Once your tutorial proposal is accepted by the maintainers, there several options for editing the tutorial and for submitting it to the Earth Engine community repository:

Markdown quick start

You can fork the GitHub repository and create a new tutorial directly via the GitHub website to quickly get started without additional tools or setup:

  1. If you haven't already, sign into GitHub.

  2. To create and edit a new tutorial file, click New tutorial. You'll be prompted to fork the repository, if needed.

    New tutorial

  3. Enter a name for the tutorial file of the form:

    your-tutorial-name/index.md

    Where your-tutorial-name is the short name of your tutorial in all lowercase. Use dashes ("-") to separate words. Do not use spaces or any other punctuation in the folder name.

  4. Edit your tutorial directly in the GitHub file editor, using "Preview" to verify the formatted output (see also Editing files in your repository in the GitHub documentation).

  5. Once ready, commit your changes and open a pull request.

Colab notebook

Click here to get started writing a tutorial in Colab:

New Colab tutorial

This will open a notebook containing instructions for authoring and submitting your tutorial.

Advanced

If you're already familiar with GitHub, git, and related tools, the overall process is the same for submitting both Markdown and Colab tutorials:

  1. Fork and clone the google/earthengine-community GitHub repository.

  2. Create a directory under tutorials with the slugified short name of your tutorial (e.g., tutorials/my-amazing-tutorial).

  3. Add the appropriate header for Markdown or Colab.

  4. Commit the tutorial to the new directory with the filename index.md (for Markdown) or tutorial.ipynb (for Colab). Commit images used in the tutorial to the same directory.

  5. Push the new content to your fork and open a pull request.

When creating a pull request, be sure to refer to the original proposal by its GitHub issue number in the comment section. For example, if the issue was #123, you would place the text "Closes #123" in the pull request description to reference the original proposal, and to automatically mark it as done once the tutorial is published.

Once you've opened a pull request, one or more maintainers will be assigned to review your submission. The reviewer(s) will work with you to ensure your submission is complete, correct, and that it is consistent with the Earth Engine Community Tutorial Style Guide.

Once your pull request is approved, your tutorial will be published by the repository maintainers.