-
Notifications
You must be signed in to change notification settings - Fork 276
Google Season of Docs 2024 Project
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. 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
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. After a considerable effort made last year, the documentation was finally consolidated into a single source using an attractive and familiar structure, geared to helping users easily find the information they needed based on their needs. The new system also moves away from static documentation formats, and is now embedded into the OpenQuake engine repository and continuously updated alongside the code. This allows a better way to keep track of changes, taking advantage of the version control offered by Git.
The current problem that we intend to tackle this year has to do with the experience of new users. The problem can be divided in the following parts:
-
Installation Instructions At present, the resources available that deal with installation instructions are from 2020, and thus are completely outdated. Furthermore, there are no installation resources for all of the operating systems and options that the software can support (combinations of Windows, Linux and Mac installed on laptops, servers, clusters or cloud).
-
Community Support Currently, the OpenQuake engine has an active community of over 800 users that provide support through the OpenQuake users forum. This forum, however, gets a relatively high number of questions (around 3 per day) and is mostly managed by staff members from the GEM Foundation. A lot of resources are spent answering similar questions from new users.
-
Training Material Most of the training material available is relatively outdated and only available through walkthrough videos with exercises on the different modules of the engine. There is a need to make a consolidated effort into updating the current material, create text-based tutorials and explore important cases that are currently not being explained.
-
Input parameter documentation The software has evolved and new parameters have been included in the input files that are required to run calculations in the engine. Not all of the fields, or the options for existing fields, are currently included in the documentation and this causes confusion on new users that lack the experience with previous versions of the engine and have seen its evolution over the years.
-
Glossary of terms Currently the documentation has two sections on Glossary of Terms, one in the User Guide and one in the Underlying Science section. These are very useful resources for new users that are currently divided and difficult to find in the existing documentation.
The Consolidation for OpenQuake Engine Documentation project will:
- Redesign the installation section of the documentation and create content to thoroughly document the installation instructions of the current version of the OpenQuake engine, on all supported operating systems
- Research the OpenQuake users forum to understand what are the issues that new users are asking more frequently, create answers appropriate for the current version of the engine and include them in a Frequently Asked Questions (FAQs) section in the documentation
- Review the current status of the training material to determine missing modules and create resources, both in video and text format, for existing and new training modules.
- Make a comprehensive list of all the parameters and options that are available in the input/configuration files for the current version of the engine; and update the documentation of existing and missing parameters, including examples and cross references when appropriate
- Consolidate and expand the currently available Glossary of Terms sections into a single location, to be highlighted in the Getting Started section.
Work that is out-of-scope for this project:
- Aside from the points mentioned previously, 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.
The metrics that will be used to track the results of the project are related to three main components: the number of installation instruction options that are available in the site; the decrease of the number of questions received in the support forum; and the perceived satisfaction from new OpenQuake users (measured with a survey of users that have under a year of using the software).
We would consider the project successful if, three months after publication of the new documentation:
- The documentation covers at least 80% of the available installation options.
- A decrease in the month-over-month number or questions received in the OpenQuake user forum.
- The perceived rating of the OpenQuake documentation, as evidenced by the results from the surveys to be carried out to new users, at the beginning and end of the project, increases by 20%
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 inventory of existing resources and definition of the content required to remediate the identified problems (two more weeks), and finally work the last three months on creating the defined content and populating it to the documentation (through proposal, review and approval cycles with internal staff).
| Dates | Action Items |
|---|---|
| May | ▸ Orientation |
| ▸ Inventory of existing installation material and proposed content to produce | |
| ▸ Inventory of existing training material and proposed content to produce | |
| ▸ Identification of FAQs | |
| ▸ Inventory of possible input/configuration parameters available in new version of the engine | |
| June - July | ▸ Create all identified content required to remedy the associated problems |
| ▸ Merge, update and relocate Glossary of Terms | |
| ▸ Populate branch of repository with all proposed content | |
| August | ▸ Review of contributions made to the documentation |
| ▸ Final changes requested by project members | |
| ▸ Contributions to the documentation goes live | |
| November | ▸ Application of final documentation survey |
| ▸ Writing of project completion report |
| Budget item | Amount | Running Total | Notes/justifications |
|---|---|---|---|
| Technical writer of the OpenQuake Engine | $ 6,000 | $ 6,000 | Equivalent amount to 5,500 €, the contract with the technical writer will be given in Euros, since the organization is located in Italy |
| Project swag (30 t-shirts) | $ 600 | $ 6,600 | |
| TOTAL | $ 6,600 |
-
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. Furthermore, the team had a very positive experience participating in the 2023 version of the Season of Docs initiative, building a great relationship with our technical writer and obtaining an increase of 25% in user satisfaction after the implementation of the results of the programme.
-
Previous participation in Google Season of Docs, Google Summer of Code or others: As mentioned previously, the GEM Foundation and its software OpenQuake engine participated in the 2023 edition of the Season of Docs initiative. It was considered by everyone involved (users, writers, participating technical team and management) to be a great success. We are looking forward to repeating the exercise and taking advantage of the experience gained in the previous version of the programme.
If you are an experienced OpenQuake user, who is interested to collaborate with the GEM Foundation in the Google Season of Docs 2024 as a Technical Writer, please send a statement of interest to: [email protected]. Please note that we will only respond to applications from users with previous experience in using the OpenQuake engine.
Feedback on the current document and suggestions for possible improvement are very welcome. Please use the OpenQuake-engine users and developers mailing list to communicate with the GEM science and IT teams:
https://groups.google.com/g/openquake-users