Documenting Arti for The Tor Project

At DocumentWrite, The Tor Project, known for its commitment to maintaining internet anonymity and security, reached out to help us create clear and accessible documentation that will provide support to the developers and non-technical users of Arti, a Rust-based implementation of the Tor client, aimed at improving online privacy and security for the Tor network.

This case study explains how the project was planned, executed, and what the results were, highlighting the strategies used to ensure the documentation was clear, thorough, and user-friendly. By working closely with the Tor Project team and focusing on continuous feedback, the Arti documentation project achieved its goals, showing the importance of high-quality documentation in open-source software.

Objectives

The main goal of this project was to improve the quality of existing documentation, create, and build documentation that will help C Tor users find the migration to Arti easy. This was further broken down to:

1. Consolidate all documentation for Arti to one single platform.
2. Improve the quality and accessibility of existing documentation.
3. Improve the information architecture.
4. Provide conceptual and procedural guides that will support both technical and non-technical audience.

The Process

Creating comprehensive documentation for Arti involved several key steps, from initial planning, to content development, to website deployment.

1. Kickoff & Planning

To start off, we had a kickoff meeting with the Tor team to align on the documentation goals, our approach to working with each other, defining the process for reviews, tools to work with, and other relevant things for both teams to get acquainted with each other. After a few sessions, we were able to break down the project and objectives into milestones based on our recommendation. With the milestones, we also defined our process into:

• Research
• Information architecture
• Repository setup
• Content development
• Deployment & Maintenance

2. Research

This process was spearheaded by another team member, but I’ll explain the process. At DocumentWrite, we use a content audit template to help us structure the audit and present our clients with a comprehensive research report.

Firstly, we created a documentation inventory of existing documentation containing, the URL, title, and type of documentation for each page. Then, using our documentation checklist, we analysed the different types of documentation present in the Arti documentation. Next, an instructions audit was carried out to test each page with instructions to see if the instructions were complete, accurate, and up-to-date.

With all of the data that had been collected, we created a scorecard of the overall quality of the existing documentation, and provided recommendations based on the scoring. This scoring is ranked with the following in mind.

• Accessibility - Is it easy for users to read and understand the documentation?
• Purposefulness - How easy is it for users to accomplish a goal?
• Discoverability - Can users navigate your documentation and find relevant content?
• Accuracy - Is the documentation correct and up-to-date?
• Completeness - Does it cover every feature in the API?
• Consistency - Are the formatting and structure the same throughout the documentation?

We also conducted user experience interviews with 3 developers that use C Tor, and had card sorting exercises with a group of 3 other Tor users. From these exercises, we were able to determine the how best to structure information and what users might need that were missing.

3. Information architecture

After analysing the all the data from the research, I created a sitemap to improve the information architecture of the documentation site. On the sitemap, I defined the entry points, top-level menus, and other forms of navigation(categories and subcategories) that make finding information easier for users.

The sitemap also included some newly proposed pieces of content, and the existing content with possible updates. Me and my team, along with the Tor team, worked together to review and update the sitemap, making sure it was easy to understand for everyone, whether they were technical or not.

4. Repository setup

Once the sitemap was approved, I went on to setup and customise the Docusaurus website. Using Docusaurus and Gitlab, we used the Docs-as-code approach to create, review and update new and existing documentation content. To also ease the review process, I setup a skeleton of the documentation’s structure in the repository as proposed on the approved sitemap. By implementing this, we were able to limit changes to 1 per merge request. This helped us track changes easily.

5. Content development

Following the setup, I got straight to work on the writing. Using a sheet to manage the status of our progress, I worked with my manager to review and proofread every one of them. For each guide, I first drafted an outline that covers all the areas of the topic, then wrote detailed documentation for each section, ensuring clarity and conciseness. After implementing suggestions from my manager, I opened a MR allowing a member of the Tor team review, give feedback and approval for merge.

6. Deployment & Maintenance

After merging all the MRs to the main branch, tying lose ends, and cleaning up the repo, it was time to go live. We deployed the website using Gitlab Pages, and started to prep for handoff. Because this was a one-off project, maintenance is handled by the TorProject team.

7. Handoff

Before handing off all project assets, I created guides to help the Tor team handle maintenance. I also recorded video tutorials to help visualise the processes as written in the guides.

Challenges & Solutions

1. Technical Complexity:

   Documenting a complex technical project like Arti required deep understanding, and with no previous experience with the Rust programming language, it was a tough one. Though, after watching a few tutorials on Youtube, I was able to get the basic understanding I needed to work with Rust. I also worked closely with developers, participated in team meetings, and reviewed code to gain necessary insights.

2. Limited Resources:

   Since Arti is still in its early stages, I relied heavily on my own experience with Arti and insights from the engineers. This approach ensured accuracy, as every process was tested before being documented.

Outcomes

The Arti documentation project yielded several positive outcomes, significantly enhancing the usability and effectiveness of the documentation:

1. Consolidated Documentation:

   • Outcome: All relevant information about Arti was brought together in one comprehensive, easily accessible location.
   • Impact: Users no longer need to search through disparate sources to find the information they need, leading to a more efficient and cohesive user experience.

2. Produced and Updated Guides:

   • Outcome: Detailed guides were created and regularly updated to reflect the latest developments and features of Arti.
   • Impact: Users have access to up-to-date and accurate instructions, helping them navigate and utilise Arti effectively.

3. Improved Information Architecture:

   • Outcome: The documentation was reorganised with a clear, logical structure using a sitemap.
   • Impact: This made it easier for users to find and understand the information they need, enhancing the overall usability of the documentation.

4. Enhanced Consistency:

   • Outcome: Consistent terminology, formatting, and style were applied throughout the documentation.
   • Impact: Improved consistency helped in reducing confusion and provided a more professional and polished appearance, making the documentation more reliable and user-friendly.

These outcomes collectively contributed to a higher quality of documentation for Arti, facilitating better adoption and user satisfaction.