GSoD 2021 Project Proposal

Improve discoverability of content

Technical writers interested in this project see contact.

About STE||AR Group and HPX

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.

About the project

The problem

The HPX documentation has evolved over the life of the project to be extensive, but hard to navigate. It contains information about many parts of the project, but users regularly struggle to find relevant information, as evidenced by the questions and requests we see on our IRC channel. In addition to content being hard to find, some information, especially build instructions, is also outdated.

Project scope

The aim of the project is to:

• Collect feedback from the core developers, former GSoC students (of which there are several who are still active within the project), and users on difficult to discover or navigate parts of the documentation. As an example, build instructions are either very basic very detailed, but they are found in different parts of the documentation and the relationship between the two sections is not obvious (previous feedback from a GSoC student). From our experience users often struggle already at the first step of building/getting HPX. We would recommend focusing on 2-3 sections/chapters of the documentation that users find most important or confusing.
• Based on the feedback from the previous step evaluate if the top-level structure of the documentation would benefit from changes, and if yes, appropriately rearrange the chapters of the documentation. If not, focus on restructuring individual sections to make sure that they can be followed easily by new users.
• 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.

Out of scope:

• Create new content. We welcome new content but it needs to be thought of in the context of the full documentation before being added, to avoid making the problem this project is trying to solve worse.

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

We 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.