Google Season of Docs 2019
- Kate Sammons
What is HySDS?
The Hybrid Cloud Science Data System (HySDS) is a science data system framework that can leverage a heteregeneous set of worker nodes from private and public clouds as well as virtual and bare-metal machines to perform every aspect of the traditional science data system.
The HySDS framework was developed at the NASA Jet Propulsion Laboratory (JPL) over a number of years, before being released as open source software on GitHub.com in October 2017 under the Apache Software license, Version 2.0. It is currently being developed for use on a number of NASA earth science missions, including ARIA, GRFN, SMAP, SWOT, and NISAR.
Why are we participating in Google Season of Docs?
Our goal in participating in the Google Season of Docs is to get assistance in technical documentation so we can better engage the open source community outside JPL.
HySDS has been open source since October 2017, which has allowed us to collaborate with users and developers outside of JPL. However, although we have generated a lot of documentation for our users and developers, it is not organized or discoverable. It is, in fact, scattered across multiple wikis, some of which are not accessible to outside users.
We plan on consolidating all our documentation to this wiki and all our issues to our Jira system. However, we need help in structuring our documentation and making it more discoverable.
Quick links
- https://developers.google.com/season-of-docs/docs/timeline
- https://developers.google.com/season-of-docs/docs/admin-guide
Roles
- Hook Hua, organization administrator
- Sujen Shah, alternative organization administrator & mentor
- Lan Dang, mentor
Season of Docs Project Ideas
Community Wiki Management
Through the use of Confluence templates, labels, and macros, we hope to build a wiki that makes it easy to both discover and contribute to documentation. See
- Templates - make it easy for the contributor to know what should be recorded, as well as how to organize it. It makes content more readable because it will follow a certain pattern. It will also format the page to enable better use of macros to build navigation pages.
- Labels - make content more discoverable
- Macros - make it easier to generate search pages or curated lists
We also need to set up a process for designated contributors to ensure the wiki remains curated and well-organized.
Better Release Documentation
The HySDS framework is used by an increasing number of missions, and the framework is evolving rapidly according to the needs of our stakeholders. At the same time, it has become hard to communicate these changes and their impacts on a diverse group of users who may be on various version of the core framework, and who may be operating on a diverse arrangement of on-premise, private, and public cloud configurations.
We need to develop a structured changelog or release documentation process that makes it clear what has changed and how that will impact the end-user. More importantly, we need to make it semi-automated in how we pull out this information from source control comments and Jira issues, to ensure that we don't overlook any important changes.
https://keepachangelog.com/en/1.0.0/
Start up a Contributor Guide
For the past few months, we have been holding/wiki/spaces/v3/pages/137068608 to work through our governance model and our process for contributing to HySDS.
We could use help with putting together a framework for that documentation, as well as sample documents, so we can put together an easy-to-read contributor guide.
The Python Developer's Guide is something to aspire to.