Ensembl is part of the first Google Season of Docs!

by ·Comments Off on Ensembl is part of the first Google Season of Docs!

Google Season of Docs (GSoD) provides a framework for technical writers and open source projects to work together remotely towards the common goal of improving an open source project’s documentation. This exciting new programme ran for the first time from September to November 2019!

During the programme technical writers spend a few months working closely with an open source community, such as the Ensembl project. They bring their technical writing expertise to the project’s documentation and at the same time learn about the open source project and new technologies. The technical writer receives a stipend for their work from Google and can build their portfolio while the open source organisation gets valuable help and external input on their documentation.

In this first GSoD round, the number of projects was limited so both technical writers and source organisations went through a competitive selection process. Ensembl’s mentors Astrid Gall and Beth Flint have been lucky to work with Laurel Michaels, who talks about her background and project on the Ensembl REST API documentation in this blog.

My background

I am a tech writer with experience in REST API doc. The last few projects I worked on had me focused on non-REST areas of technology. Wanting to get back into working on REST API doc, I was happy to get accepted for the Ensembl REST API GSoD project. It has been both fun and interesting to learn about the Ensembl REST API implementation as well as to learn about what people who use the REST API need to get started.

Mentors

Astrid Gall and Beth Flint

Project

Create introductory, getting started documentation for people wanting to access Ensembl data via the REST API.

Project overview

Although Ensembl’s documentation included extensive reference information for the Ensembl REST API, the doc lacked a comprehensive, user-friendly getting started section for anybody who is new to the REST API. The GSoD project provides this needed getting started section.

To start, the new getting started doc introduces the Ensembl REST API capabilities, then moves on to quick hands-on tutorials and Ensembl-specific URL information and examples. It concludes with scripting shortcuts and tips for Python, Perl, and R scripts.

Specific sections include:

  • Introduction to Ensembl’s language agnostic REST API and how you can use it to both access Ensembl’s gene, variation, comparative genomics as well as regulation data and to analyse variation data
  • Authentication information
  • A few examples to get you started: a quick example to test your connection, then a slightly deeper dive into retrieving information from the Ensembl database
  • How URLs are structured, including examples and mappings to how this information is provided in the Ensembl REST API reference doc
  • Scripting tips for Python, Perl, and R
  • Links to additional help resources

GitHub

You can find the preview of the new Getting Started Guide in this repository:
https://github.com/EnsemblGSOC/GSOD-REST-lmichaels/wiki
We plan to add it to our existing documentation soon.