Documenting tor’s governance processes

overview

Tor is well known for providing privacy and anonymity on the internet, through its network, allowing users to browse the internet without revealing their identity or location. The Tor network achieves this by routing encrypted traffic through a series of volunteer-run servers or “relays” that protect its users.

With numerous volunteers, and committed to transparency and openness, Tor’s relay community governance documentation serves as a foundational guide, highlighting the processes, policies and structures that govern the operation and use of Tor relays.

why relay governance documentation critical to Tor’s mission

The core of the Tor network is built on relays operated by volunteers all over the world. This means, to prevent the abuse and misuse of relays, certain processes are set in place for the community to follow.

For globally-managed open-source projects like Tor, governance documentation is an important tool that’s beneficial to the project and its community. In The Tor Project’s case, this governance documentation also serves as commitment to its users. As noted in Tor’s Social Contract #2, Tor is committed to transparency; so, everything they release is open, and their development happens in the open.

As Tor’s network of relays operators grow, so does the complexity of its governance needs, with input from a wide range of contributors and stakeholders. This documentation needed to reflect Tor’s transparency, empowering contributors to make informed decisions concerning relay operations, and engage effectively within the community.

Key objectives included:

• Making policies easily understandable and usable by both new and existing relay operators.
• Establishing a single, authoritative source of truth for Tor’s governance practices (in relation to relays).
• Reinforcing Tor’s values of privacy, security, and transparency by aligning internal processes with its public commitments.

the challenges

In decentralised open-source environments like The Tor Project, the need to strike a balance between diverse stakeholder interests, ensuring transparency, and maintaining flexibility, brings about complexities on governance and its documentation. Unlike traditional organisations, Tor’s decisions involve a variety of contributors and volunteers, each bringing different expectations, levels of expertise, and cultural perspectives.

With this structure, there is need for documentation that is accessible and understandable to both technical experts and general community members, while also being robust enough to handle different interpretations of policies. Additionally, the open-source nature of Tor means that contributors may have limited time and occasional involvement, making it critical for documentation to provide clear, immediate guidance without extensive onboarding.

In Tor’s existing documentation, a few gaps affecting how contributors understood and navigated Tor’s governance processes were identified.

1. The documentation lacked clear explanations of specific roles and responsibilities, leading to confusion about who could make certain decisions or take specific actions.

This gap made it difficult for new contributors to engage effectively and for long-term members to coordinate their efforts efficiently. 2. The documentation did not adequately capture why specific measures were chosen, nor did it specify why others were rejected. This absence leaves both new and existing contributors perplexed about the logic and reasoning underlying crucial governance decisions. 3. The lack of guidance on handling conflicts or decision-making in ambiguous scenarios created friction, as contributors had no standard approach to resolve these issues, impacting both collaboration and efficiency. 4. Although relay operators are integral to the Tor network's success, the documentation lacked clear, community-driven behavioural agreements and defined consequences for non-compliance. This gap leaves ambiguity around acceptable practices, enforcement standards, and operator responsibilities.

research and information gathering

To build a foundational understanding of Tor’s governance, I started with a detailed review of any existing governance documents, public meeting notes, and community guidelines. This included exploring both formal documents and informal resources, like community forums, and mailing lists, to capture the nuances of Tor’s decentralised structure. This was followed by conversations with core members of Tor’s Network Health team for discussions on the basic understanding developed.

Additionally, I reviewed similar open-source projects to gain insights into common governance challenges and structures within communities, providing valuable context to Tor’s unique environment. To get the whole picture, I looked at how policies affected various stakeholders, from relay operators to occasional contributions. This helped me to reconcile the intended goals of formal governance with the practical concerns raised by the community, resulting in a more comprehensive point of view.

Interviews and discussions with stakeholders were instrumental in defining my documentation approach. Speaking with core contributors and project leads provided first-hand insights into their challenges and expectations. For example, feedback from core members relayed specific concerns around security, and disclosing some operational details to avoid accidentally supporting bad actors, emphasising the importance of striking a balance between transparency and security in the documentation. These conversations led me to prioritise transparency, context, and clarity, as well as to carefully analyse sensitive information to ensure the documentation aligned with Tor’s ethics and security standards.

structuring the documentation

In structuring the documentation for Tor's relay community governance processes, several key factors guided my decisions.

1. Focusing on the diverse audience who would interact with the documentation, including not just experienced contributors but also new relay operators and community members, to build a framework that accommodates different levels of expertise with the content, ensuring that important information is readily available.
2. Examining the necessity for a modular format that allows users to get to certain parts related to their interests or tasks without having to hunt through large amounts of text. This resulted in the establishment of distinct headings and subheadings that effectively define themes, making it simple for users to find the information they require.

the outcome:

content development and writing process

To make complex governance processes comprehensible, I used a user-centric writing style that emphasised clarity and simplicity. I boiled down complex concepts into manageable chunks, using simple language and accessible examples to highlight essential themes. Additionally, I used modular sections and clear titles to help users browse the text simply.

When confronted with conflicting information or ambiguous governance policies, I worked to explain the situation through interactions with stakeholders, including core team members and community contributors. I hoped to find common ground and clear up uncertainties by fostering conversations about different points of view. In circumstances where policies were changing, I made it obvious in the documentation that certain sections were open to modification, offering context for why decisions were reached and emphasising the continuing nature of governance conversations. This transparency contributed to managing user expectations and building trust in the documentation.

To gather feedback, I implemented a collaborative review process that involved stakeholders from Tor’s Network Health team. After initial drafts were completed, I shared them through Gitlab, inviting comments and suggestions.

overcoming project-specific challenges

One of the challenges that arose during these revision rounds was balancing differing opinions, as some stakeholders had strong, opposing views on certain governance aspects. Additionally, the iterative nature of this process required multiple rounds of revisions, which sometimes extended timelines. However, these challenges ultimately led to a more comprehensive and representative final document that better served the community’s needs.

Given the diverse sources and perspectives involved, there were frequent differences in interpretation and terminology. To address this issue, I used an existing glossary of key terms and definitions to ensure consistency throughout the material.

Managing sensitive material required a cautious approach to ensure that operational security was not jeopardised, therefore I collaborated closely with core team members to determine which facts could be securely provided while certain technical features remained classified. I also provided comprehensive reasons for why some decisions were made, demonstrating Tor's commitment to transparency and accountability.

The final documentation: Tor Relay Community Governance

impact and value of the documentation

The relay community governance documentation promotes Tor's mission by outlining expectations, rights, and obligations within its open-source community, creating a transparent atmosphere in which contributors feel educated and empowered.

By detailing governance processes and behavioural rules, it provides a structured framework for involvement, making it easier for new and existing contributors to understand how to participate effectively while adhering to community standards. This transparency has increased contributors' trust in Tor's governance and facilitated collaboration across different teams.

reflections and best practices

This project demonstrated the need of balancing transparency and security in governance documentation for open-source communities. One major takeaway was the importance of collaboration; working closely with stakeholders and contributors enabled me to generate documentation that accurately reflects community needs and ideals. I also discovered that modular, accessible information structure is critical in a decentralised system where contributors have various levels of experience with the community and its processes.

This experience also deepened my understanding of the nuances involved in documenting processes for open-source projects. Unlike traditional corporate settings, open-source governance requires clear documentation that respects both autonomy and collective accountability. It made me more aware of the unique challenges in conveying policies that uphold community values, while allowing for flexibility as the project evolves.

For technical writers in similar positions (writing documentation for open-source projects and communities), I recommend prioritising accessibility and involving community members early and often in the process. Ensure clarity by breaking down complex topics into manageable sections, and use visual aids wherever possible. Another best practice is to establish clear feedback loops with stakeholders to catch ambiguities or potential conflicts early on.

Document not only what governance policies are in place but also the rationale behind them, so contributors understand the guiding principles and context for decisions.