docs/pdds/pdd00_pdd.pod

   1 # Copyright (C) 2001-2010, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 PDD 0: Design Document Format
   5
   6 =head2 Abstract
   7
   8 This document defines the content and format of Parrot Design Documents
   9 (PDDs).
  10
  11 =head2 Version
  12
  13 $Revision$
  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 Abstract:
 103
 104 A quick blurb explaining the purpose of the PDD.
 105
 106 =item Synopsis I<(optional)>:
 107
 108 Code snippets showing the semantics of the PDD (if applicable).
 109
 110 =item Description:
 111
 112 A description of the general nature of the PDD and how it relates to
 113 Parrot.
 114
 115 =item Implementation:
 116
 117 A major section of the PDD that encapsulates a free-form discussion of any and
 118 all applicable information related to the final observations, conclusions, and
 119 what-have-you that required writing the document in the first place.
 120
 121 =item Attachments:
 122
 123 References to supporting files that should be considered part of the PDD.
 124 Text files and image files may be in any widely accepted format, which is
 125 rather subjective.  Violators may be prosecuted.
 126
 127 Text files and image files should only provide supplemental information; no
 128 fair hiding all the info in an attachment just to not have to write an
 129 implementation section.
 130
 131 =item References:
 132
 133 References to additional sources of information, but not those necessary for
 134 the PDD itself.
 135
 136 =back
 137
 138 The PDD author may add any additional sections he or she wishes.
 139
 140 =head3 Submission Criteria
 141
 142 Proposed PDDs should be submitted to the parrot-dev mailing list (located
 143 at parrot-dev@lists.parrot.org) for discussion, criticism and general
 144 kibitzing.
 145
 146 Acceptance of a particular PDD is ultimately up to the Parrot Architect.
 147
 148 =head3 PDD Translations
 149
 150 Translations of PDDs into other languages should meet these guidelines:
 151
 152 =over 4
 153
 154 =item *
 155
 156 The C<Version> section should include an additional note of the translated
 157 version.
 158
 159 =back
 160
 161 =head2 References
 162
 163 None.
 164
 165 =cut
 166
 167 __END__
 168 Local Variables:
 169   fill-column:78
 170 End: