This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- HPX
- Technical writer:
- rstobaugh
- Project name:
- Edit & Streamline Existing HPX Documentation
- Project length:
- Standard length (3 months)
Project description
My proposal is to edit and streamline the content of the existing HPX documentation. My proposal is for a standard term (three month) project that focuses on revising two chapters of the STE||AR group’s manual: ""HPX Build System and Launching"" (1) and ""Configuring HPX Applications"" (2).
The chapter on ""HPX Build System and Launching"" has several grammatical errors and also contains confusing language and inconsistent capitalization of terms like “CMake.” Moreover, it contains repeated information, which I plan to rearrange, consolidate, and trim as needed. While the chapter on ""Configuring HPX Applications"" also contains a few grammatical errors that need to be addressed, my primary concern for this chapter is its user friendliness. The chapter has three major design issues I plan to address:
Some headings are buried within the text, making it hard to skim through the chapter. Currently, a user would need to read though the manual carefully to understand the purpose of each table. This is not how most users interact with instruction manuals, especially if they have already read though the content before. Instead, I plan to make sure each table has a clear, distinct heading, which can be easily seen if a user scrolls through the text.
When listing various properties under a particular heading, the properties do not follow a logical order. While properties are grouped together under a common theme, there are no subgroupings, which makes information feel scattered. For example, a user may encounter several properties that deal with locality, a few that deal with another subject, then another that deals with locality. This lack of internal structure under headings makes it harder to locate all information on a specific subtopic. Therefore, I plan to reorganize several of the charts to more clearly group similar information together under each heading.
Users are forced to navigate back and forth between sections (or open the manual in two separate tabs) to fully understand certain instructions. There are points where the chapter directs the user to a single sentence within a previous section in a manner that forces the reader to scroll up or follow a hyperlink to understand the exact instruction, as the manual uses vague language like “this step is preformed after step 11” in the previous section. While this method does eliminate repetition, it makes it harder to understand the instructions, as these are tasks that need to be preformed in a specific order. Instead, I propose including more specific wording so that users do not have to interrupt their reading process by switching between sections or documents.
If I complete these sections before the standard timeline is finished, I would also like to clean up the “Why HPX?” (3) page under the STE||AR group’s User Documentation. This page contains repetitive introductory content, which I hope to consolidate and contains inconsistencies in capitalization (particularly of jargon) and voice, which give it a disunified feel. My goal would be to create a more unified, consistent introduction to the STE||AR group’s work.