Update 05/01: TERRA REF was not selected for the inaugural season of docs, but we plan to re-apply next year. But check out the impressive list of organizations who will be participating in GSOD 2019, a who's who of open software projects.
TERRA REF has applied to participate in the inaugural Google Season of Docs.
Season of Docs is a unique program that pairs technical writers with open source mentors to introduce the technical writer to an open source community and provide guidance while the writer works on a real world open source project. The technical writer in turn provides documentation expertise to the open source organization.
TERRA REF is developing open data, software, and computing to advance the sensing of plants, with the aim of developing crops that are more productive, stress tolerant, and efficient at using resources including water. Our homepage is terraref.org, our GitHub organization is github.com/terraref, our documentation is at docs.terraref.org and we have tutorials at terraref.org/tutorials.
In April we applied to be a Google Season of Docs mentor organization, with the goal of finding technical writers who are interested in helping us better communicate what we have to offer to a range of interested end users, and effectively communicate the data and software that we are producing, and how to use it. Our audience includes those interested in learning about our research, using the data we are generating, developers interested in contributing to our computing pipeline or adapting our software to their own pipelines, engineers interested in our sensing and analysis technologies, and the public. We have a lot to offer, and need help presenting it clearly!
Project ideas
This page provides a list of specific projects ideas for technical writers in developing during the 2019 GSOD. Please feel free to mix, match, and propose alternatives based on your current expertise, new skills and technologies that you want to learn, and generally what you want what you want to get out of this experience!
Project 1: Refactor the current documentation.
Divide the documentation at docs.terraref.org into distinct components aimed at specific user groups including: the generally curious, researchers seeking data, software developers, and end users of the sensing platform. This documentation is currently hosted on GitBook, but could optinoally be migrated (in whole or part) to bookdown or another markdown based framework. This project can include separating material into basic overview and technical manuals, migrating protocols to protocols.io, and moving examples into our tutorials.
Project 2: Improve and extend tutorials.
These tutorials introduce users with a variety of methods with which they can quickly get started using the data that we are generating. Currently they are maintained in the tutorials repository in our github organization, github.com/terraref/tutorials, and the objective of this project is to review and revise these for clarity and to target them at specific audiences. Currently these tutorials focus on accessing and analyzing data using command line software languages R and Python, but could be extended to include tutorials for accessing the data in web and desktop user interfaces.
Project 3: Compile and publish algorithm descriptions.
Each algorithm that we use in the pipeline should have a comprehensive and consistent description aimed at allowing technical experts to understand and use the code. Many of the algorithms already have such descriptions, and these are maintained in separate README files that are spread across different repositories in our organization (github.com/terraref) on GitHub . Maintaining the README files alongside the code is a useful, but it makes it difficult to find and evaluate all of the documentation at once. For example this one for the hyperspectral camera calibration and this one for estimating percentage of ground covered by plants in photographs. The project would 1) develop a template that scientists could use to define an algorithm that they have contributed and 2) implement a system for compiling README and other documentation files scattered across multiple repositories into a single book.