Further improve discoverability of content

Technical writers interested in this project see contact.

About STE||AR Group and HPX

The STE||AR Group aims 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 aligns closely with the C++ Standard and the ongoing 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 struggle to get started with HPX due to the complexity of the concepts and the lack of discoverability of existing documentation. To make our project more accessible and user-friendly, we need to improve the discoverability and approachability of our documentation. This will help us expand our user base and allow us to provide more focused assistance to users on advanced topics.

About the project

The problem

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.

Project scope

The aim of the project is to:

• Write from scratch new example use cases of HPX and provide code snippets for two cases:

  1. 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.
  2. 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.

Measuring your project’s success

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.

Project budget

Item	Amount
Technical writer restructures documentation	5000
Swag for volunteer proof-reading	200
TOTAL	5200

Additional information

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.

Contact

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.