symbol Asset 1

RNP proposal for Google's Season of Docs 2021

Author’s picture Ronald Tse on 26 Mar 2021

This is our proposal for Google’s Season of Docs 2021.

Technical writers: please contact us if you are interested in helping improve RNP documentation!

Google Season of Docs 2021 logo
Figure 1. Google Season of Docs 2021 logo

This is the proposal for Google’s Season of Docs 2021.

About RNP

RNP (https://www.rnpgp.org) is an open-source, openly-licensed (BSD-3) cryptography suite, which aims to facilitate usable end-to-end encryption based on zero-trust. Its high-performance C++ library provides a set of cryptographic primitives fully compliant with the OpenPGP standard (IETF RFC 4880).

First created in 2017, RNP is now used by Mozilla’s Thunderbird to enable end-to-end encryption across its 35+ million users, enabling Thunderbird to be the world’s most popular mail client that supports end-to-end encryption. RNP has undergone heavy security testing by Mozilla and Cure53, with public security reports provided on the Internet.

The RNP suite is officially supported and funded by the Mozilla Open Source Support (MOSS) Foundational Technology and Secure Open Source funds, and the EU Horizons 2020 program through NLNet’s Next Generation Internet initiative.

The following individuals of the project community have offered to act as volunteer mentors for this project:

  • Daniel Wyatt, Lead Developer of the RNP OpenPGP library. IETF standards participant, previously at FEMA. Contributor to multiple cryptographic tools including OpenSSL, LibreSSL, Botan. 3 times Google Summer of Code participant.

  • Dr. Wai Kit Wong, Head of Research at Ribose. Published heavily in cryptographic cloud systems. Former Associate Professor in Computer Science and Head of the Department of Computing at Hang Seng University of Hong Kong.

Project description

Current status

Due to rising popularity of the RNP project, the speedy growth of its userbase (and the need to address user needs) has caused development at RNP to outpace documentation efforts.

There are two aspects in RNP that need better documentation: the CLI and the API.

Currently, RNP provides minimal API documentation as an integrated library, which is insufficient for most developers who need to perform native integration, and inadequate for those who utilize RNP from the command line.

Better documentation will aid more pairs of eyes to review and improve adoption of the RNP library, which will help expose undiscovered problems in RNP.

This category of work aims to provide a reference guide for both the library and CLI, and provide a set of guides for easier adoption of the RNP components.

Identified issues

  1. Documentation of code with on-going development is an ongoing challenge for developers.

    • This issue becomes especially pronounced when the development team is paced by user needs, where time constraints generally leave code documentation at a dismal and outdated state. Developers are known not to be best at technical writing and it is important that the right skill set is applied for this problem.

  2. Existing documentation is outpaced by development efforts.

    • Outdated documentation causes problems ranging from minor inconveniences (e.g. users need to search for code changes) to potential security risks (e.g. users utilize outdated cryptographic code).

  3. Streamlining automated documentation for code documentation.

    • Maintaining documentation separate from the codebase requires context-switching and creates friction between the programming and documenting processes.

Project scope

Deliverable: Audit report of the current state of documentation

  • Familiarize and audit existing documentation and software

  • Develop an understanding of existing community needs

  • Strengths and weaknesses of current documentation

  • Perform usability test on existing documentation and identify parts most difficult to follow

Deliverable: Information architecture and use case prioritization

  • Prioritize use case focus by using the usability test results to develop more comprehensive documentation

  • The desired information architecture should:

    • Allow the audience to discover the information they need;

    • Use a layered approach, where the audience can learn more detailed information step-by-step, allowing the novice to progress in knowledge without being overwhelmed; and

    • Be understandable to the suitable audience. Documentation for CLI is geared towards the normal user, while documentation for API is geared towards the software developer. We need to ensure that these audiences can find what they need.

Deliverable: Library API documentation

  • Author a detailed library API reference guide for each component to allow users the ability to find details of library API usage

  • Documentation should be built in an automated way through code annotations

Deliverable: CLI documentation

  • Author a detailed CLI reference guide to allow users the ability to utilize the CLI

  • Documentation should be built in an automated way through code annotations

Deliverable: How-to guides

  • Author how-to guide to allow users to easily adopt RNP on a personal computer or for an organization

  • Documentation should be built in a code-centric manner for better automation

Deliverable: GSoD project case study

  • Authored by the technical writer and interested project mentors

  • Describes the success and challenges faced during the GSoD project for future reference

Work considered out-of-scope:

  • This project is of a pilot nature due to the budget amount - we do not expect every available API signature to be documented to the brim.

  • This project will not address documentation on how RNP can be used with other systems (e.g. software that rely on RNP)

We are seeking a competent open-source technical writer who has an interest in information security and willing to learn about the topic.

Potential impact of the project

RNP powers 35+ million installs of Mozilla Thunderbird, and its adoption as an open alternative to existing OpenPGP tools is going strong, especially for civil society and for those that depend on privacy for safety.

Improved documentation for RNP will enable both typical Internet users and power users to better protect their privacy through adopting RNP.

Measuring project’s success

Expected results

The developed documentation will be published on the RNP project website at https://www.rnpgp.org.

  • Goal: A layman user can read the CLI user guide to install, setup, generate keys, and utilize RNP to protect information and send signed/encrypted emails; a developer can read the API guide to compile, setup and utilize RNP in the developer’s application.

    • Indication metric: Amount of people referring to the user guides.

  • Goal: Allow code annotations to be developed into documentation in an automated fashion

    • Indication metric: Number of times that developers have to switch from code annotations to document content on the official website

Measurable project metrics

Two goals are sought of the project:

  1. provide detailed and updated documentation to bring more users into the community.

    • This can be reflected by the number of new users of project documentation.

  2. make updating documentation as automated and as easy as possible.

    • This can be reflected by the number of PRs on rnpgp.org for contributing documentation that did not originate from code annotations.

The project would be considered successful if, after the project:

  • Unique traffic to project documentation increases by 10%; and

  • Number of code-documentation PRs to rnpgp.org decreases by 20%.

Project schedule

Project Length

3 months

Project Plan

Item Duration (month)

Technical writer acclimatizes to existing project documentation and seeks clarifications from mentors.

0.5

Technical writer develops a high-level structure of deliverables under mentorship.

0.5

Technical writer develops contents of deliverables with progress overseen by mentors.

1.5

Technical writer facilitates testing of the developed deliverables by seeking public feedback and project contributors. Finalizes deliverables addressing community feedback.

0.5

Total

3

Budget

Item Amount Running Total Notes/justifications

Technical writer

4,800.00

4,800.00

Swag

200

5,000.00

Project T-shirts (with shipping)

Additional Information

The RNP project has mainly been documented by its technical contributors. One of our mentors, Daniel Wyatt, has participated in the Google Summer of Code program as a participant three times!