docs/pdds/pdd00_pdd.pod

   1 # Copyright (C) 2001-2008, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 PDD 0: Design Document Format
   5
   6 =head2 Version
   7
   8 $Revision$
   9
  10 =head2 Abstract
  11
  12 This document defines the content and format of Parrot Design Documents
  13 (PDDs).
  14
  15 =head2 Synopsis
  16
  17 Not applicable.
  18
  19 =head2 Description
  20
  21 PDDs are living documents, which should be maintained to reflect the current
  22 and contemplated design of Parrot.
  23
  24 The key aspects of Parrot's design are its interface to the outside world --
  25 its feature set -- and its internal structure, both in code and in the broader
  26 project.  Thus, PDDs describe Parrot's:
  27
  28 =over 4
  29
  30 =item *
  31
  32 I<Codable interfaces>: headers, functions, macros, file formats, etc.
  33
  34 =item *
  35
  36 I<Structural requirements> that the implementation must obey: resource usage,
  37 portability, modularity, interdependency, etc.
  38
  39 =item *
  40
  41 I<Abstract models> that the implementation expresses or conforms to.  These
  42 models are in some sense meta-designs, because they provide guidance for the
  43 evolution of the current design.
  44
  45 =item *
  46
  47 More? - FIXME
  48
  49 =back
  50
  51 PDDs don't generally discuss the implementation details.  Low-level
  52 implementation documentation, the maintainer's guides, should go in the
  53 relevant F<docs/dev/*.pod> file.
  54
  55 PDDs may document design trade-offs, i.e. the paths not chosen. In many cases
  56 they don't, just to keep the PDDs relatively short and readable. The history
  57 of Parrot's design is retrievable from the source repository.
  58
  59 =head2 Implementation
  60
  61 All newly created PDDs will adhere to the PDD standard current as of the time
  62 of proposal. An example of the currently accepted layout is given in
  63 F<docs/pdds/pdd_template.pod>, which should be used as a template for any
  64 future PDDs.
  65
  66 =head3 Format
  67
  68 All PDDs will be written in POD parseable by the current stable release of
  69 Perl 5. Although XML is a viable solution and has its vocal supporters, and
  70 although Parrot is intended to be used by many groups outside of the Perl
  71 community, we have chosen POD for its simplicity and ease of reading in
  72 plaintext form.  Conversion to other formats (e.g. HTML) is encouraged, but
  73 the master version must be POD.
  74
  75 All PDDs will be written in English.  The choice of British, American, or
  76 Other is up to the author.  Translation to other languages, like all Perl
  77 documentation, is encouraged.  (See S<L<"PDD TRANSLATIONS">>.)
  78
  79 PDDs should be word-wrapped at column 78.  For Emacs variants, this can be
  80 arranged by putting these lines at the end of the file, after "=cut":
  81
  82     Local Variables:
  83       fill-column:78
  84     End:
  85
  86 See L<pdd_template.pod> for the basic structure of a PDD.  Notes on the
  87 sections:
  88
  89 =over 4
  90
  91 =item I<name>:
  92
  93 A short, general description of a specific part of the Parrot design. This may
  94 be a particular subsystem (e.g. the garbage collector), or a more general
  95 topic (e.g. basic Parrot datatypes).
  96
  97 =item Version:
  98
  99 Document version.  Since Parrot is currently kept in a Subversion repository,
 100 the $$-delimited keyword "Revision" will do nicely.
 101
 102 =item Maintainer I<(optional)>:
 103
 104 The name and current email address for the point of contact for the PDD. This
 105 is the person to whom questions, comments, and patches should generally be
 106 addressed. This need not be the author of the document.  By default, all PDDs
 107 are maintained by the Parrot Architect.
 108
 109 =item Abstract:
 110
 111 A quick blurb explaining the purpose of the PDD.
 112
 113 =item Synopsis I<(optional)>:
 114
 115 Code snippets showing the semantics of the PDD (if applicable).
 116
 117 =item Description:
 118
 119 A description of the general nature of the PDD and how it relates to
 120 Parrot.
 121
 122 =item Implementation:
 123
 124 A major section of the PDD that encapsulates a free-form discussion of any and
 125 all applicable information related to the final observations, conclusions, and
 126 what-have-you that required writing the document in the first place.
 127
 128 =item Attachments:
 129
 130 References to supporting files that should be considered part of the PDD.
 131 Text files and image files may be in any widely accepted format, which is
 132 rather subjective.  Violators may be prosecuted.
 133
 134 Text files and image files should only provide supplemental information; no
 135 fair hiding all the info in an attachment just to not have to write an
 136 implementation section.
 137
 138 =item References:
 139
 140 References to additional sources of information, but not those necessary for
 141 the PDD itself.
 142
 143 =back
 144
 145 The PDD author may add any additional sections he or she wishes.
 146
 147 =head3 Submission Criteria
 148
 149 Proposed PDDs should be submitted to the parrot-dev mailing list (located
 150 at parrot-dev@lists.parrot.org) for discussion, criticism and general
 151 kibitzing.
 152 Acceptance of a particular PDD is ultimately up to the Parrot Architect.
 153
 154 =head3 PDD Translations
 155
 156 Translations of PDDs into other languages should meet these guidelines:
 157
 158 =over 4
 159
 160 =item *
 161
 162 The C<Maintainer> section should record who made the translation.
 163
 164 =item *
 165
 166 The C<Version> section should include an additional note of the translation
 167 version.
 168
 169 =back
 170
 171 =head2 Attachments
 172
 173 (none)
 174
 175 =head2 References
 176
 177 (none)
 178
 179 =cut
 180
 181 __END__
 182 Local Variables:
 183   fill-column:78
 184 End: