Season of Docs 2024 project proposal
This page describes our proposed project for the 2024 Google Season of Docs.
FontTools (current version 4.49.0; first release 1991) is an MIT-licensed Python library for manipulating fonts. It provides modules and command-line tools for building, decompiling, troubleshooting, analyzing, drawing, and experimenting with font data in a variety of contemporary and historical font formats, including TrueType, OpenType, AFM, UFO, and several platform-specific file formats. FontTools is used in high-volume font-production build chains by both individual typeface designers and by font foundries, it provides scripting interfaces and core functionality for GUI font editors both proprietary and open source, and it is used by creative artists for drawing, illustrating, and creating generative design pieces.
The wide diversity of use-cases that draws users to fontTools makes it difficult to provide documentation that meets everyone's need for information and instructive examples. Font-engineering modules contributed by community members for a commercial font editor like Robofont one month may be used in an interactive drawing tool like DrawBot the next month. Users can find it difficult to navigate the documentation of individual modules or sub-libraries and understand how to combine elements to achieve what they want. This leads to a significant number of "how to" questions being asked in online discussion spaces and to questions being filed as issues on the main repository.
For convenience, the project is titled "Complete module references and users' guides" to communicate the intended scope and goals of the proposed work.
The proposed documentation project will:
-
Audit the existing documentation and frequently-asked-questions in the issue tracker and discussion channels.
-
Use the audit and question records to identify which fontTools modules and sub-libraries exhibit gaps in the current documentation, and which end-user use cases are in need of specialized "users guide" material in the form of dedicated introductory manuals or new code examples, then create and extend documentation for the principle modules, libraries, and use cases.
-
Seek out and incorporate feedback from the fontTools user and contributor community.
-
Draft a guidebook to help contributors incorporate new or updated documentation in their future branches and pull requests.
We have identified a technical writing candidate who has a proven track record for documentation projects, familiarity with the fontTools codebase, and a thorough understanding of font technology. The maintainers of fontTools are committed to supporting this project.
The fontTools project receives multiple direct questions or requests for help each month through the issue trackers of its main repository and of its secondary repositories. But it also receives many others via online discussion channels and through the repositories or discussion forums of related third-party software projects, either by the project or maintainers being tagged in issues and threads. We will track the number of direct questions on our repositories and channels as a first-order metric and assess the pattern that can be observed in third-party software projects as a second-order metric.
We will also audit the number of modules, classes, and methods in the fontTools codebase that are currently undocumented or feature only boilerplate documentation.
We would consider the project a success if the newly created documentation results in a 30% reduction in direct requests for help or information, and if 80% or more of the currently under-documented components of the library are successfully documented.
The project will take approximately four months to complete. Once a technical writer has been hired, we expect to spend one month on the audit phase, and the remaining three months completing the individual documentation sections and documentation guidebook.
The new documentation will be implemented primarily using our existing Read The Docs documentation infrastructure, augmented where necessary by interactive Python notebooks.
We expect the only budget item required to be the contracting of a technical writer, and are requesting a grant of US$15000 to complete the work described in the time frame specified.