Writing your first Community Tutorial

Our user community is continuously using the Earth Engine platform to build novel and impactful applications. This space is dedicated to our prolific and talented users who want to share their own hands-on guides 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 guides to walk throughs of more advanced techniques.

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

Before you begin

Code of Conduct

The Earth Engine team is committed to fostering a welcoming community. Please familiarize yourself with our Code of Conduct before participating.

Joining GitHub

Earth Engine Community Tutorials are shared and reviewed through the popular GitHub platform. If you don't already have a GitHub account, you can create one here.

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 develop tutorials that will be useful to the Earth Engine developer community. It also saves time by avoiding additional 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 style guide:

    View the 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. Fork the repository and start editing a new tutorial file:

    New tutorial

  2. 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.

  3. 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).

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

Colab notebook

Click here to get started writing a ipynb 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 repo.

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

  3. 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.

  4. 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 proprosal, 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.