Grant Proposal: Establishing Documentation Standards for the Perl 7 Era
Thu, 30-Jul-2020 by
Jason A. Crome
edit post
<, generalizing my experience with that project into a set of guidelines for creating and updating Perl's documentation for the modern era -- and then proving these standards against a sample selection of current documentation.
The advent of Perl 7 presents us with an opportunity to re-examine and refresh the language's vast collection of documentation, following the mandate set by Sawyer X to re-tune Perl with accessibility to new users as a primary focus.
In the spirit of Perl's affinity for memorable attribute-triplets, I assert that the documentation for this new era should espouse these principles:
* **Consistency**: Speak with one trustworthy voice, and with a specific audience in mind: a resident of the early-to-mid 21st century who wishes to learn Perl.
* **Clarity**: Write clearly and concisely, free of jargon, digressions, or other distractions that may confuse the material at hand.
* **Accuracy**: Draw upon decades of community knowledge and experience to deliver definitive and accurate information about the language.
This project would deliver a framework to guide future revisions and additions to Perl's documentation to better adhere to these values.
## Your name
Jason McIntosh
## Benefits of the project to the Perl Community
This work will give Perl a solid foundation from which to launch a thorough examination and overhaul of its own "first-party" documentation -- the dozens of `/perl.*/` manual pages, the hundreds of `perlfunc` sub-entries, and the hundreds more individually documented core modules that all ship with Perl.
These standards will help the Perl community critically review and tighten the focus of its own voluminous legacy documentation to better match the newcomers-first spirit of Perl 7. It will provide a guiding light required by a goal of that magnitude, and help define the path for subsequent documentation-revision projects.
Specifically, I envision the standard serving as the first step in a chain of projects aiming to evaluate and overhaul Perl 7's inherited documentation collection. As a separate follow-on project, these standards could define a rubric for categorizing the quality, relevance, and needs of every page of the core Perl docs. This would in turn define further projects to actually revise these docs, all according to the community-accepted principles laid out in these new standards.
No matter its ultimate use, the work proposed here would draw strength from the language's deep history, while looking forward to define its best shape.
## Deliverables
As its main component, this project's deliverables include a set of best practices for the documentation included with Perl itself -- whether that of language features, built-in functions, or core modules.
This new document would define a "living standard" owned by the community at large, and open to future tuning and adaptation as required. I propose to lead the project of composing its initial draft, working with P5P and other experts through the whole process.
This proposal leaves the published format of these standards as something to determine later, with input from the community; I anticipate either a Perl manual page or a porting document.
In order to illustrate its efficacy, the deliverables will also include annotated examples of how the new standards would apply to a small sampling of extant Perl documentation. If time allows, given the requested budget of this project, I will also submit these revised manual pages to P5P as proposed documentation patches.
## Project details and a proposed schedule
I anticipate that achieving the deliverable will involve the following sources:
* Any "meta-documentation" that already exists for Perl, such as the `perlpodstyle` man page by Russ Allbery
* The documentation standards of other general-purpose, open-source programming languages
* Consultation with the Perl community, including but not limited to authors of extant documentation
* Consultation with documentation and related experts outside the Perl community
* My own experiences from revising `open` and `perlopentut`, including the community feedback and insights gained from that work
Upon achieving a first draft of a standards document, I intend to "prove" it against a small sampling of extant core Perl documentation, no more than three to five examples. I will annotate, as part of the deliverable, how well each such document adheres to the proposed standards. I will offer illustrative revisions to sample documentation that falls short of the new standard -- submitting these revisions as documentation patches to Perl, when appropriate.
I would expect to complete the first step -- drafting a complete standards document, including iterative, community-driven revisions -- within two months of the grant's approval. I anticipate delivery of the annotated documentation examples within two additional months.
## Your biography
An independent writer and technology consultant based in New York, I have used Perl as my primary programming language since the previous century. More recently I have become active in releasing Perl-based software of my own authorship as open-source projects, such as [Plerd](https://github.com/jmacdotorg/plerd), a static-site blogging platform.
My past writing about Perl has included co-authorship of one book ("Perl & XML", with Erik T. Ray), and documentation patches to various CPAN-based projects, as well as to Perl itself. In early 2020, I delivered a TPF grant-funded project to overhaul the core documentation to Perl's `open` function, as well as its `perlopentut` manual page.
My personal website is at <https://jmac.org>, and my email address is <jmac@jmac.org>.
## The requested amount
I estimate $3,000 for this project.
This breaks down to a $50/hour rate for my time, multiplied by an expected 50 hours, with a supplementary $500 budget for additional expenditures incurred during research. (This may involve hiring assistance from additional experts.)
My final report will include a detailed accounting of time and materials spent on this project, reflected in the final amount requested. I will not allow the balance to exceed $3,000 without written approval from The Perl Foundation.
]]>
Comments (0)
