Skip to content

Latest commit

 

History

History
85 lines (57 loc) · 3.08 KB

README_revisions.pod

File metadata and controls

85 lines (57 loc) · 3.08 KB
Raw

NAME

docs/README_revisions.pod - Readme file for the revision of Parrot's Documentation

DESCRIPTION

This README sets out a brief overview of the Parrot Community's effort to revise its Documentation Set. The goal of this revision effort is to ensure Parrot's documentation meets or exceeds the highest standards of the Parrot Community, but, equally, to ensure it meets or exceeds the needs and the reasonable expectations of both Parrot's developers and Parrot's user base, to wit: Accessibility and Usability. Efficient, effective, accessible, and usable documentation to aid Parrot's developers and Parrot's users to achieve their development objective is the loadstone by which we will guide our revision efforts.

The principal milestones of this effort are,

  • a thorough review and complete update of all current, relevant documentation;

  • the identification and the archival, where appropriate, of any and all obsolete documentation;

  • the completion of a three volume set, comprised of

    • a Developer Manual - consisting of an explanatory Part I and an implementation specific Part II on the Parrot VM;

    • a User Manual - consisting of an explanatory Part I and a practical Part II on how to develop a High-Level Language on the Parrot VM; and

    • a Reference Manual - consisting of a detailed reference on the internals of the Parrot VM.

  • a revision and update of the PIR book contained in docs/book/pir;

  • a revision and update of the PCT book contained in docs/book/pct;

  • the creation of Perl5 Pod manpages, which will then be autogen-ed into *roff manpages, for all of the installable binaries in the Parrot distribution;

  • the creation of an autogen indexer, which will generate an easy reference index, for the Parrot Documentation Set;

  • the implementation of such protocols and methodologies as are necessary to ensure Parrot's code documentation comports with Parrot's internal coding standards; and

  • the creation of a new, friendlier front page for parrot.org.

Clearly, as the above list indicates, this revision effort is a nontrivial undertaking, and it will require the talents and the efforts of a great many people to bring it to fruition. But, once done, Parrot's Documentation will ... shine, which, after all, is what we are all after.

If you are interested in contributing to this revision effort, please take a look at the below How to Help section.

How to Help

Read the Parrot Developer FAQ in docs/gettingstarted.pod. It contains all of the information you need to get started helping out on Parrot. Just follow the instructions on locating and subscribing to the Developer Mailing List. Or, alternatively (or in addition to), follow the instructions on how to visit the #parrot channel on the IRC server irc.parrot.org. Either way, you will find someone ready to point you in the right direction.

COPYRIGHT

Copyright (C) 2011, Parrot Foundation.