Update HPX Manual, Examples and API - STE||AR Group

About HPX

The STE||AR Group is developing HPX, a Standard Library for Concurrency and Parallelism. HPX implements all of the facilities as defined by the C++ Standard. Additionally, in HPX we implement functionalities proposed as part of the ongoing C++ standardisation process. We also extend the C++ Standard APIs to the distributed case.

The goal of HPX is to create a high quality, freely available, open source implementation of a new programming model for conventional systems, such as classic Linux based Beowulf clusters or multi-socket highly parallel SMP nodes. At the same time, we want to have a very modular and well designed runtime system architecture which would allow us to port our implementation onto new computer system architectures. We want to use real-world applications to drive the development of the runtime system, coining out required functionalities and converging onto a stable API which will provide a smooth migration path for developers.

The API exposed by HPX is not only modelled after the interfaces defined by the C++11/14/17/20/23 ISO standard. It also adheres to the programming guidelines used by the Boost collection of C++ libraries. We aim to improve the scalability of today’s applications and to expose new levels of parallelism which are necessary to take advantage of the exascale systems of the future.

About HPX Documentation

Project’s current issues

HPX is a highly popular project that garners the attention of professionals as well as researchers and students. However, users often face challenges when attempting to use specific facilities of HPX, develop new features or even install HPX, which leads them to seek assistance in the community forum. Although we are always glad to provide support, we strongly believe that many of these issues can be resolved with proper documentation. Our current documentation is exhaustive and contains a plethora of useful information. Over the years, we have made remarkable improvements in our documentation, in part thanks to the contributions made by individuals who got to know us through previous year’s GSoD. Our efforts have been widely lauded by many contributors and users who expressed their satisfaction with the updates. In fact, our primary technical writer has been with us for the past two years after joining the group via GSoD! Thus, we eagerly look forward to engaging more people in our Open Source project!

Project’s scope

The aim of the project is to:

• Expand the examples that demonstrate the use cases of HPX:
  • Minimal examples that demonstrate the use of core API utilities, much like the documentation provided in cppreference. These examples aim to highlight the essential usage of simple functionality, providing users with a clear and concise understanding of the core features of HPX, without composing them into a larger script that performs complicated tasks.
  • Detailed examples that showcase the major functionalities of HPX and can be easily traced and modified for their own use. The past years we developed examples that parallelize algorithms such as the matrix-matrix multiplication, fibonacci etc. These can serve as a starting point for creating beginner, intermediate, and advanced usage examples. Through this tutorial-like series of examples, users will be able to access a range of helpful resources that enable them to fully leverage the power of HPX.
• Audit the existing documentation of the existing Manual and apply changes that:
  • Update or enhance the instructions for building HPX. While this section is already detailed, we recognize that there are still many people who encounter difficulties when attempting to install HPX on their system. Therefore, we believe it would be helpful to provide a user-friendly guide that provides step-by-step instructions for beginners. Our current information is adequate for advanced users, but beginners may require more explicit guidance. Additionally, we plan to include a dedicated page or subsection that highlights the most common mistakes that people make when installing HPX, along with effective strategies for preventing them. This will enable users to quickly and easily troubleshoot any issues they may encounter during the installation process.
  • Many pages of the manual were written some time ago, and as a result, they may contain obsolete information. To address this, we plan to revisit certain sections of the manual and update the contained information. While some pages have already been updated, there is still work to be done to ensure that all of the information provided is current and accurate. By revisiting these pages, we can ensure that users have access to the most up-to-date and reliable documentation available.
• Update API Reference:
  • A clear and comprehensive API reference is essential for developers who wish to build applications using HPX, or to contribute to the project. The Public API page has undergone significant changes in recent years, but given the extensive nature of our API, we are committed to ensuring that it includes details for all available functions, methods, and classes, along with their parameters and return values. Our goal is to provide developers with the most comprehensive and up-to-date reference available, enabling them to build powerful and reliable applications with ease.
• Extend contributor's guide:
  • Over the past few years, our primary focus has been to update the User Guide. We noticed that HPX users tend to face more difficulties compared to contributors who are already familiar with the system. As a result, we have not updated our contributor's guide in some time. We believe that an improved version of our guide would make it easier to encourage new contributors.

As this is a comprehensive list that requires substantial changes to the documentation's content, we do not expect our technical writer to complete all of the aforementioned tasks. We strongly believe that people are more productive when they work on projects that interest them. Therefore, we leave it open to our applicants to select one or two projects they are particularly passionate about and would like to focus on.

Measuring our project’s success

Last year HPX received an average of 27 pull requests per month to add or update code or documentation. The majority of these pull requests are from previous contributors. We believe that this improved documentation will result in more pull requests from new contributors. Since many of our active contributors began either by GSoD or GSoC, we appreciate the initiative of GSoD to support Open Source projects and we believe this is a great opportunity for our project to get bigger.

We will use a survey method (Q&A) to ask users and contributors how they feel about the updates of the documentation. Since the GSoC period is overlapping with the anticipated GSoD project time, we believe this is a great opportunity to evaluate how fast people will familiarise themselves with HPX before and after the documentation changes.

We would consider the project successful if after publication of the new documentation:

• More than 80% of the people participating in the survey declared to be happy with the updates.
• We see a slight increase in the Pull Requests, which will mean that people understand faster how to use and develop features of HPX.
• We see newcomers being able to familiarize themselves with HPX without explicit guidance from a previous member.
• Members of the group find it easier to use new features or/and have a clear guideline on how to structure new content of and where to place it. Of course, we hope to be able to keep the technical writer involved in the project past the end of the project as well.

Timeline

The project itself will take approximately six months to complete. Once the tech writer is hired, we'll spend a month on tech writer orientation, then move onto the development of documentation depending on the projects chosen by the technical writer. An example-timeline is provided below.

Dates	Action Items
May	Orientation
June - August	Write examples/Update API
September - October	Create documentation
November	Project completion

Project budget

Item	Amount	Running Total	Notes
Technical writer restructures documentation	5000	5000
Swag for volunteer proof-reading	500	6000	2 volunteer stipends x 500 each
TOTAL		6000

Additional information

Previous experience with technical writers or documentation

Our mentors have extensive experience working with technical writers, as one of them is technical writers themselves. Our current technical writer joined us during GSoD 2020 and has continued to make significant contributions to our documentation. Over the years, we have made substantial improvements to the documentation, including updating the theme and layout to make it more user-friendly and readable, enhancing the API reference, and updating many pages of the Manual, Examples, and Quickstart guide.

To ensure a thorough review process, we hold regular meetings where we discuss the technical writer's progress and next steps. Additionally, our group forum is always available, and we have an active community that is eager to answer questions. Through this experience, we have learned how to effectively organise our work and mentor individuals while maintaining their interest.

Previous participation in Google Season of Docs and Google Summer of Code

In recent years, our project has been selected to participate in both GSoC and GSoD programs, providing us with valuable experience and opportunities to promote the quality of our project and support its goals. This year, we have already been accepted for GSoC, and we have received a lot of interest from individuals who are eager to participate in our project. This experience will help us further improve our project this year during GSoD, should we be selected.