GSoD 2022 Project Proposal
Technical writers interested in this project see contact.
The goal of the STE||AR Group is to promote the development of scalable parallel applications by providing a community for ideas, a framework for collaboration, and a platform for communicating these concepts to the broader community.
HPX, developed by the STE||AR Group, is a C++ library for concurrency and parallelism. It implements APIs defined in the C++ Standard Library and extends them to work in a distributed memory space. In this way HPX exposes a unified programming model which transparently utilizes available resources. Our work is closely aligned with the C++ Standard and the ongoing C++ standardization process. HPX receives contributions from a diverse range of academic and volunteer developers. The project was started over 10 years ago and is used in many open-source projects. New users often require significant help in getting started, in part due to the difficulty of the concepts, but in part also due to lack of discoverability of content that already exists. Presenting our documentation in a more approachable and easily discoverable way would help the project expand its user base and allow focusing on helping users directly with more difficult topics.
The HPX documentation has evolved over the life of the project to be extensive, but hard to navigate. Although we experienced a successful GSoD 2021 run there is still plenty of room for improvement. Our main focus this year is on the API restructuring and how users will be able to access it and navigate through it. Since our documentation contains information about many parts of the project users regularly struggle to find relevant information, as evidenced by the questions and requests we see on our IRC channel.
The aim of the project is to:
-
Write from scratch new example use cases of HPX and provide code snippets for two cases:
- Full representative examples that utilize major HPX functionalities and users will be able to trace and compose in order to use HPX. Last year we developed a matric multiplication example. This can be extended to beginner, intermediate and advanced usage examples for the users to be able to access a narrow tutorial-like series of examples.
- Minimal use cases (5-10 liners) that showcase the usage of core API utilities. These are different kind of examples since they will utilize isolated parts of HPX without composing them into a greater script that would do complicated work. It would rather demonstrate essential usage of simple functionality.
Various examples already do exist throughout our documentation. The writer will have the option to collect them and provide a uniform web interface for the users to access them.
-
Expand on the API documentation and work towards ephasizing and unifying the C++ Standard conformance of HPX. Beyond decoupling and improving the aesthetics of our API, we would like to provide further linkage on corresponding C++ Standard facilities that are implemented in HPX.
-
Create a "design document" containing guidelines for how to add new content to the documentation: tips on how to structure new sections, general guidelines on what sort of content should be presented in what chapters, etc.
The scope of the project is flexible as it can easily be divided into sub-projects, each focusing on a particular chapter or section. However, considering the time to get started and acquainted with the project, and leaving enough time for the project to have a significant impact we estimate 3 months of work.
We will collect direct responses from the users who give us feedback on what parts of the documentation could be made more discoverable, which will tell us immediately if the documentation is improving. This will likely be an ongoing process during the project. In addition, we will conduct a new user survey at the end of the project to collect feedback from a wider range of users. We previously conducted a survey in the beginning of 2020 which we can use to evaluate improvements to the documentation. Finally, if developers who previously contributed documentation have a clear guideline by the end of the project on how to structure new content and where to place it we will be able to keep the quality of the documentation stable even if a technical writer is no longer involved. Of course, we hope to be able to keep the technical writer involved in the project past the end of the project as well.
| Item | Amount |
|---|---|
| Technical writer restructures documentation | 5000 |
| Swag for volunteer proof-reading | 200 |
| TOTAL | 5200 |
HPX's existing documentation can be found here. While it's already quite extensive, it has grown organically and needs restructuring and heavy editing. We recently moved our documentation to Sphinx for better navigation, but the content remained mostly unchanged. One problem is that the documentation contains a lot of information, which means that beginners can often struggle to find what they're looking for. At the same time, we don't want more advanced users to feel like they can't find what they're looking for.
The HPX documentation is written using reStructuredText and rendered using Sphinx. Familiarity with these is helpful but not required as reStructuredText is easy to pick up. In addition, since HPX is mostly implemented in C++, at least a basic level of familiarity with C++ will be helpful in understanding code examples and concepts explained in the documentation.
Our last Google Season of Docs run was the previous year (2021) and resulted in a fruitful collaboration with Dimitra Karatza that was even extended beyond the program. Our technical writer did a tremendous job on providing a brand new Sphinx interface for our documentation and improved navigation. Dimitra also fixed our How to build HPX guide and made it more user-friendly for newcommers. A matrix-multiplication use case scenario example was provided that exposed the HPX parallel algorithms functionality and improvements also took place on the grouping of our API into specific sections.
We also participated in Google Season of Docs 2019 where the technical writer worked on the project Edit and streamline the content of the existing HPX documentation. She was supposed to work on only a few of sections of the documentation, but was able to go through all of our existing documentation and even continued her contributions after the GSoD period. She contributed 22 pull requests in total during and after Season of Docs. She focused mostly on language on correcting and improving language in our documentation which is why we are now proposing this project to focus on structure instead.
We had an amazing learning experience improving our documentation during Season of Docs 2019, and we are applying again based on this positive experience. We believe that the technical writer improves their skills by working on a completely new project/codebase, while we benefit from the improvements in our documentation. Furthermore, our open-source contributors learn to write cogent documentation from the technical know-how that the writer brings to the table.
Our organization has also taken part in Google Summer of Code six times mentoring around 25 students in total, which has given the organization significant experience in helping people get going with the project, and in making sure they achieve their goals during the project.
If you're a technical writer interested in working with the STE||AR Group on improving HPX's documentation get in contact with us. IRC and Matrix are recommended since those see the most activity. Please be patient if you do not receive a reply immediately as we are all spread across different timezones and it may take some time for a Season of Docs admin/mentor to see your message.
-
Abstract: HPX is largely modeled on existing or proposed C++ standard library functionality. While it's often enough to point users to standard library documentation (e.g., cppreference) as the HPX implementations usually follow the standard, it makes for a less than ideal experience for users as they have to jump between two different sites to learn about the HPX APIs. In some cases, the HPX APIs extend the standard facilities, and the standard documentation is not sufficient for users. This project aims to document such functionality within HPX for easier access for users. Examples of such un- or underdocumented features are
future,async,tuple,optional,any. Presenting our API documentation in a better way can be combined with this project. - Deliverable: New and/or corrected documentation for facilities corresponding to standard facilities.
-
Mentors: Parsa Amini (
), Giannis Gonidelis (gonidelis[at]hotmail.com)
- Abstract: As part of the move to Sphinx as a documentation system, the quality of presentation of our API documentation was reduced. As we're also planning a new major release of HPX and intend to specify the public API, a more curated presentation of the API may be a better experience for users. This project aims to take our current API documentation and present it in a more user-friendly way, either through the existing tools (Doxygen and Sphinx), through Sphinx extensions (Breathe), or tools completely outside of Sphinx (standalone Doxygen). The current API documentation is presented here in a largely unstructured way.
- Deliverable: Restructured API documentation.
-
Mentors: Parsa Amini (), Giannis Gonidelis (gonidelis[at]hotmail.com)
- Abstract: There are several HPX tutorials (e.g., HPX Workshop at HLRS - 2019) that implement example applications that are useful beginners. Some of these examples (e.g., Fibonacci, 1D Stencil) are included in the HPX documentation, and some are not. The objective of this project is to add these tutorials to the HPX documentation.
- Deliverable: New tutorials in HPX documentation based on existing code and other presentation material
-
Mentors: Parsa Amini (), Giannis Gonidelis (gonidelis[at]hotmail.com)
- Abstract: We always appreciate volunteer contributions to HPX but think that the process could be made easier to encourage new contributors. Our contributor's guide should be as straightforward as possible and contain the necessary steps for a new contributor to go from building to testing and submitting a pull request. Currently, there is only a minimal amount of information in the "Developer documentation" section of our documentation. In addition, there is scattered information for contributors in this wiki.
- Deliverable: A new contributor's guide in our documentation to consolidates the existing information in the documentation and this wiki and expands it if needed with missing information.
-
Mentors: Parsa Amini (), Giannis Gonidelis (gonidelis[at]hotmail.com)
- Abstract: The HPX documentation currently contains headers that can be re-organized to enable quicker lookup and generate more intuitive documentation. Consider, for instance, comprehensive build instructions for HPX are found hidden under the manual header. While basic build instructions exist under quick start, a better alternative would be to have a "build instructions" header that takes you through the quick install and a step-by-step guide for cases when the former method throws CMake or compiler errors. The project aims at improving the visibility of certain headers through re-organizations.
- Deliverable: Restructured documentation layout with more intuitive headers and general sentence improvements.
- Mentors: Nikunj Gupta (gnikunj@cct.lsu.edu), Giannis Gonidelis (gonidelis@hotmail.com)