# 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 Version
$Revision$
=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:
