# Copyright (C) 2001-2010, Parrot Foundation. =head1 PDD 0: Design Document Format =head2 Abstract This document defines the content and format of Parrot Design Documents (PDDs). =head2 Synopsis Not applicable. =head2 Description 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 describe Parrot's: =over 4 =item * I<Codable interfaces>: headers, functions, macros, file formats, etc. =item * I<Structural requirements> that the implementation must obey: resource usage, portability, modularity, interdependency, etc. =item * I<Abstract models> that the implementation expresses or conforms to. These models are in some sense meta-designs, because they provide guidance for the evolution of the current design. =item * More? - FIXME =back PDDs don't generally discuss the implementation details. Low-level implementation documentation, the maintainer's guides, should go in the relevant F<docs/dev/*.pod> file. PDDs may document design trade-offs, i.e. the paths not chosen. In many cases they don't, just to keep the PDDs relatively short and readable. The history of Parrot's design is retrievable from the source repository. =head2 Implementation 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 F<docs/pdds/pdd_template.pod>, which should be used as a template for any future PDDs. =head3 Format All PDDs will be written in POD parseable by the current stable release of Perl 5. 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 S<L<"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 L<pdd_template.pod> for the basic structure of a PDD. Notes on the sections: =over 4 =item I<name>: A short, general description of a specific part of the Parrot design. This may be a particular subsystem (e.g. the garbage collector), or a more general topic (e.g. basic Parrot datatypes). =item Abstract: A quick blurb explaining the purpose of the PDD. =item Synopsis I<(optional)>: Code snippets showing the semantics of the PDD (if applicable). =item Description: A description of the general nature of the PDD and how it relates to Parrot. =item Implementation: A major section of the PDD that encapsulates a free-form discussion of any and all applicable information related to the final observations, conclusions, and what-have-you that required writing the document in the first place. =item Attachments: References to supporting files that should be considered part of the PDD. Text files and image files may be in any widely accepted format, which is rather subjective. Violators may be prosecuted. Text files and image files should only provide supplemental information; no fair hiding all the info in an attachment just to not have to write an implementation section. =item References: References to additional sources of information, but not those necessary for the PDD itself. =back The PDD author may add any additional sections he or she wishes. =head3 Submission Criteria Proposed PDDs should be submitted to the parrot-dev mailing list (located at parrot-dev@lists.parrot.org) for discussion, criticism and general kibitzing. Acceptance of a particular PDD is ultimately up to the Parrot Architect. =head3 PDD Translations Translations of PDDs into other languages should meet these guidelines: =over 4 =item * The C<Version> section should include an additional note of the translated version. =back =head2 References None. =cut __END__ Local Variables: fill-column:78 End: