Google Season of Docs 2023 Project

Consolidation of OpenQuake Engine Documentation

Outcome of the proposal

The GEM Foundation and its OpenQuake-Engine project are thrilled to have been accepted into the Google Season of Docs 2023 program. The project management staff has decided to hire Basar Yucel, an experienced OpenQuake user and earthquake engineer, as Technical Writer for this year's contribution to the OpenQuake Documentation.

The application process for this year is closed. GEM Foundation appreciates all candidates that have applied to the position, you will be considered for future opportunities.

About the GEM Foundation and the OpenQuake-engine

The Global Earthquake Model Foundation (GEM) is a non-governmental organization (NGO) with the mandate to calculate and communicate earthquake hazard and risk worldwide. Through its international network of experts, regional collaborations, and global projects, GEM leads and facilitates the development of tools, models, and datasets that support the creation of risk reduction strategies. GEM is a unique organization due to its scientific credibility, global coverage, and commitment to openness and transparency. ​ Since its foundation in 2009, GEM has supported a number of global projects that have resulted in databases of tectonic faults, buildings and infrastructure exposed to earthquakes, seismic fragility and vulnerability models, and a classification system to categorize buildings worldwide. These efforts involved more than 200 international experts and the resulting products are currently being used extensively by the disaster risk reduction community, academic institutions, engineering companies, and the insurance sector. During these years, GEM has also developed an open-source software for the assessment of earthquake hazard and risk, named the OpenQuake-engine (https://github.com/gem/oq-engine). This tool has been used for the derivation of national hazard maps in various nations such as Colombia, Turkey, Italy, Taiwan, Armenia, New Zealand, Australia and Canada; which have been incorporated in the respective design regulations. Furthermore, OpenQuake has been used to create seismic risk profiles for most countries in the world. These efforts led to the development of global earthquake hazard and risk maps, which were initially released in 2018, being the first in its kind in terms of coverage and quality. ​ Over the years since its launch, the OpenQuake-engine has become the worldwide benchmark tool, with which earthquake scientists develop their hazard and risk models, as well as run their calculations. The outputs from these studies and models, provide valuable information to local governments and public organizations, allowing them to assess their risk to earthquakes and ultimately take actions to build resilience to these catastrophic events.

More information available online at www.globalquakemodel.org ​

The Problem

Even though the OpenQuake project has been widely adopted by the earthquake science and engineering community and has had significant impact already within its first decade of existence, with a staff of fewer than 30 employees, of which only a few are dedicated exclusively to the development of OpenQuake, some aspects of the software (particularly its documentation) have lagged. Currently, the existing OpenQuake documentation is in different formats and scattered across different locations, ranging from:

• the project GitHub repository, which contains installation instructions, FAQs, and a few one-off sphinx-generated HTML doc pages
• sphinx-generated HTML doc sites for its basic user manual and advanced user manual
• a YouTube channel containing playlists of video tutorials, and
• static PDF documents explaining the underlying earthquake hazard and risk science ​ The main outcome of the documentation project would be to restructure and consolidate all the existing information into a single location and format, following the documentation system proposed by DIVIO. ​

Project Scope

The Consolidation for OpenQuake Engine Documentation project will:

• Create a layered structure by which the existing OpenQuake documentation will be organized, following the four quadrant documentation system.
• Create a location to serve as an online repository for all existing OpenQuake documentation.
• Migrate the content of the current HTML websites for the basic and advanced user guides, following the proposed structure.
• Transform the static PDF documents for the underlying hazard and risk science, so that it can be uniformly accessed in the newly formed online repository.
• Host the locations for the relevant YouTube training videos, for each of the existing modules. ​ Work that is out-of-scope for this project:
• This project will not deal with the update of technical content or development of new documentation for currently undocumented features of the OpenQuake-engine.
• This project will not cover the documentation of other open-source software projects developed by the GEM Foundation, other than the aforementioned items relating to the OpenQuake-engine. We estimate that this work will take four months to complete. The Secretary General, overall management and key members of the GEM Foundation staff, have committed to supporting the project. ​

Tracking Project Success

The metrics that will be used to track the results of the project are related to three main components: the number of website locations that a user needs to access to review the existing OpenQuake documentation, the perceived satisfaction from OpenQuake users (measured with a survey), improvements of the SEO of the OpenQuake documentation. ​ Currently, users must navigate several locations with resources to learn about OpenQuake, this typically requires a member of staff or an experienced user to point them in the right direction; the most straightforward outcome of the project will be to consolidate all existing resources in a single location. In terms of perceived satisfaction, this is something it has never been quantified; however, it could be collected by applying a survey in the OpenQuake users forum on Google Groups, which is an active community of over 700 users. Finally, in terms of improving SEO, it is noted that currently when a user searches for “OpenQuake documentation” in Google, the top ranked result leads to a static PDF with the basic user guide. It is expected that, three months after the consolidated website is completed, this website will become the top ranked result for the same keyword search in Google. ​ We would consider the project successful if, three months after publication of the new documentation:

• The totality of existing OpenQuake documentation can be accessed through a single website
• The perceived rating of the OpenQuake documentation, as evidenced by the results from the surveys to be carried out at the beginning and end of the project, increases by 30%
• The website created for the documentation comes as a top results when searching “OpenQuake documentation” in Google ​

Timeline

The project itself will take four months to complete, followed by a three month passive period allowed to track the performance of its outputs. Once the tech writer is hired, we'll spend two weeks on tech writer orientation, then move onto the definition of the consolidated documentation structure (two more weeks), the migration of existing static documentation to HTML, and finally work the last two months on populating the newly created website for documentation with all available resources. ​

Dates	Action Items
May	▸ Orientation
	▸ Inventory of existing documentation
	▸ Definition of consolidated documentation structure
	▸ Definition and application of initial documentation satisfaction survey
June - July	▸ Migrate static documentation to HTML
	▸ Create website location for consolidated documentation
	▸ Populate website with all existing documentation
August	▸ Review and testing of consolidated documentation
	▸ Final changes requested by project members
	▸ Consolidated documentation goes live
November	▸ Application of final documentation survey
	▸ Writing of project completion report
​

Project Budget

Budget item	Amount	Running Total	Notes/justifications
Technical writer consolidation of existing documentation of the OpenQuake Engine	$ 5,310	$ 5,310	Equivalent amount to 5,000 €, the contract with the technical writer will be given in Euros, since the organization is located in Italy
Project swag (6 t-shirts, 50 stickers)	$ 150	$ 5,460
TOTAL		$ 5,460
​

Additional Information

• Previous experience with technical writers or documentation: The GEM Foundation staff has experience in writing technical software documentation since the first release of the OpenQuake Engine in 2010. The team is very capable in producing technical documentation, as evidenced by the quality of the existing resources that detail the use of OpenQuake. However, as a non-profit organization, there are limited resources to invest in improving the overall structure and functionality of the existing documentation, bringing it to current best-practices and standards. Furthermore, GEM Foundation does not have experience in bringing external technical writers to support in this task, but we hope that the Google Season of Docs initiative can provide an opportunity to derive this experience, and have this exercise be a regular part of documentation maintenance.
• Previous participation in Google Season of Docs, Google Summer of Code or others: The GEM Foundation has never participated in the application of the aforementioned grants from Google. ​