|parrotcode: Parrot Design Documents|
|Contents | Documentation|
docs/pdds/pdd00_pdd.pod - Parrot Design Documents
This document defines the content and format of Parrot Design Documents (PDDs).
PDDs are living documents, which should be maintained to reflect the current and contemplated design of Parrot.
The key aspects of Parrot's design are its interface to the outside world -- its feature set -- and its internal structure, both in code and in the broader project. Thus, PDDs descirbe Parrot's:
PDDS should not discuss the implementation details or trade-offs, unless they absolutely have to. Such implementation documentation should go in the relevant *.dev file. On the other hand, PDDs should document design trade-offs, i.e. the paths not chosen.
These guidelines may seem fuzzy. The line between "design" and "implementation" is a murky one. Still, please try to adhere to this design for Parrot design documentation. How you implement it is up to you. :-)
All newly created PDDs will adhere to the PDD standard current as of the time of proposal. An example of the currently accepted layout is given in docs/pdds/pdd_template.pod, which should be used as a template for any future PDDs.
All PDDs will be written in POD parseable by the current stable release of Perl. Although XML is a viable solution and has its vocal supporters, and although Parrot is intended to be used by many groups outside of the Perl community, we have chosen POD for its simplicity and ease of reading in plaintext form. Conversion to other formats (e.g. HTML) is encouraged, but the master version must be POD.
All PDDs will be written in English. The choice of British, American, or Other is up to the author. Translation to other languages, like all Perl documentation, is encouraged. (See "PDD TRANSLATIONS".)
PDDs should be word-wrapped at column 78. For Emacs variants, this can be arranged by putting these lines at the end of the file, after "=cut":
Local Variables: fill-column:78 End:
See pdd_template.pod for the basic structure of a PDD. Notes on the sections:
The PDD author may add any additional sections he or she wishes.
Proposed PDDs should be submitted to the perl6-internals mailing list (located at email@example.com) for discussion, criticism and general kibitzing. Acceptance of a particular PDD is ultimately up to the Parrot Architect.
Translations of PDDs into other languages should meet these guidelines:
MAINTAINERsection should record who made the translation.
VERSIONsection should include an additional note of the translation version.