Grant Proposal: Establishing Documentation Standards for the Perl 7 Era
Title
Establishing documentation standards for the Perl 7 era
Synopsis
I propose to build on my revisions to the open and perlopentut manual pages, 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 in