doc/Documentation_Standards.org

   1 #+TITLE:    Notes on documenting Org
   2 #+AUTHOR:   Phil Rooke
   3 #+EMAIL:    phil@yax.org.uk
   4 #+LANGUAGE: en
   5 #+STARTUP:  showall
   6 #+TEXT:     Notes to myself justifying the conventions and standards in my
   7 #+TEXT:     set of recent doc patches.
   8 #+OPTIONS:  H:3 num:t toc:t \n:nil @:t ::t |:t ^:nil *:t TeX:t
   9
  10 * Background
  11
  12 I think it is an express objective of Carsten's that Org should be
  13 readily accessible to all users of Emacs and not just those who might
  14 happen to read or hack on the code of this particular package.  To
  15 that end significant effort has been made and continues to be made by
  16 the Org community to ensure that high quality, user focused,
  17 documentation is readily available to everyone.
  18
  19 Org itself contains a comprehensive guide to using all aspects of the
  20 system, how to extend it yourself, and highlights some of the many
  21 burgeoning number of add-on packages that others are contributing.
  22 This guide, [[info:org:Top][The Org Manual]], concentrates on the facts of working with
  23 the system. Supplementing this, the [[Org web pages]] contain pointers to
  24 many tutorials and how-to's which capture much of spirit and
  25 imagination people show when using Org as a basis for building broader
  26 organizational systems that help them help themselves.
  27
  28 I use Org, but it is a big system, and so I happen to think that
  29 improving the consistency, clarity and accuracy of Org documents helps
  30 both me and all other users of the system.  In support of this and by
  31 way of justification and clarification, this short note attempts to
  32 capture some of the existing guidelines and standards that have been
  33 used in the patches I am submitting and, which I hope, may be adopted
  34 by others when making their own contributions.
  35
  36 * Referencing systems, packages, modes and much else
  37
  38 Originally Org was a single mode and there was no ambiguity about what
  39 Org mode could refer to.  Things have changed rapidly though and it
  40 seems that Carsten now thinks of Org as the system encompassing the
  41 major mode, some minor modes, and an increasing number of additional
  42 packages and plug-ins that build on the core Org functionality.  It is
  43 really hard to find a consistent way to refer to all these things, but
  44 what I am trying to do is follow these guidelines (which are not
  45 perfect, merely a start):
  46
  47 - In general write "Org" as much as possible and, in particular, when
  48   discussing concepts, features and functions that are generally
  49   applicable to Org as a whole.
  50
  51 - Be more specific and write, for example, "the Orgtbl minor mode"
  52   when referring to something unique to that feature.  It may be, for
  53   example, a command is only available when you are actually editing a
  54   file using just that mode, add-on package or plug-in.
  55
  56 - Prefer "Org mode" to "Org-mode" or "org-mode".  This is simply
  57   because it reflects an existing convention in [[info:emacs:Top][The Emacs Manual]] which
  58   consistently documents mode names in this form - "Text mode",
  59   "Outline mode", "Mail mode", etc.
  60
  61 - Likewise refer, if at all possible, to "Org file or "Org buffer"
  62   meaning with, great generality, any file or buffer which requires
  63   use of some part of Org to edit it properly.
  64
  65 - Org uses "org-..." to ring fence a name space for itself in the
  66   Emacs code base.  This is obviously retained in code snippets.
  67
  68 * Other Org specific conventions
  69
  70 Unless there is a good reason to do otherwise, then try and adopt the
  71 following conventions.  (I think all can be justified by reference to
  72 Carsten or precedent in other significant Emacs documentation, unless
  73 I have made them up of course).
  74
  75 - Org has *lots* of commands and a /lot/ of them take prefix arguments of
  76   one sort or another.  Write in full "prefix argument", "numeric
  77   prefix argument" or, maybe, "a numeric prefix argument N" when you
  78   want to refer to the argument again.
  79
  80 - Org lives in various states of harmony and discord with other Emacs
  81   packages.  Try and write the names of those packages as their
  82   authors and maintainers write them.  So it should be (I think) BBDB,
  83   MH-E, Rmail, VM, Gnus, CDLaTeX etc.
  84
  85 - TODO keywords, whether Org or user defined, are written in capitals.
  86
  87 - Built-in tags with a special meaning (e.g. ARCHIVE) are written in
  88   uppercase.  User defined tags (e.g. boss, home) are written in
  89   lowercase.
  90
  91 - Built-in properties (e.g. PRIORITY) are written in uppercase.  User
  92   defined properties (e.g. Release) are written in lowercase.
  93
  94 - Entries in the concept index are normally all lower case unless some
  95   other rule dictates otherwise.
  96
  97 * orgmanual.org specific conventions
  98
  99 Org git repository comes with an .org version of the manual in the
 100 =contrib/= directory.  Here are indications that are specific to this
 101 version of the manual.
 102
 103 - Five of the standard Texinfo indexes are used in the Org manual:
 104
 105   + #+cindex: :: concept index, for general concepts
 106   + #+findex: :: function index, for function and function-like names
 107   + #+kindex: :: keystroke index, for keyboard commands
 108   + #+pindex: :: program index, for names of programs
 109   + #+vindex: :: variable index, for variable names
 110
 111 - Use fixed-width area for one-line examples.
 112
 113 - Use example blocks for Org syntax instead of "begin_src org".
 114
 115 - Internal links to headlines always start with a star.
 116
 117 - Tags, node properties, are not shown with the surrounding colons.
 118
 119 - When to use = ... = or ~ ... ~ markup:
 120
 121   + files or extensions use = ... =,
 122   + anything that is meant to be written in the Org buffer uses = ... =,
 123   + any meaningful token in a programming language uses ~ ... ~.
 124
 125 * Miscellaneous
 126
 127  - Only two of the standard Texinfo indexes are used; those for
 128    concepts and keys.  This has some implications:
 129
 130    + The preference is to document commands by key rather than by name
 131
 132    + Texinfo commands such as @var and @defoption are not used.  The
 133      preference for this type of thing is that the user browses the
 134      customize groups.  If you want or need to refer to, say, a
 135      variable then document it as "the variable
 136      @code{org-startup-folded}"
 137
 138    + Entries in the concept index are normally all lower case unless
 139      some other rule dictates otherwise.
 140
 141  - Org documentation is written in American English, which is somewhat
 142    foreign as far as I am concerned, but live with it anyway.
 143
 144  - Org uses a number of compound words, words that I wouldn't
 145    necessarily run together.  Instead of worrying about whether these
 146    should be separate, hyphenated or compound I have simply gone with
 147    the majority case as originally written and then tried to make sure
 148    the spell checker knows what this chosen standard should be so that
 149    I do not worry about it anymore.
 150
 151  - I have run a spell checker periodically. Aspell works well and has
 152    a useful Texinfo filter (although, annoyingly, I cannot make this
 153    work with ispell.el and so I run it from the command line).  I have
 154    an Org specific Aspell configuration file (which sets an American
 155    dictionary, rules for compound words etc) and which, along with the
 156    associated word and replacement files, captures some of the more
 157    detailed and somewhat arbitrary rules I have used.
 158
 159  - Org has really low entry barriers.  Requirements seem simply to be:
 160
 161    + You can use Text mode or, pretty much, any derivative of it
 162    + You have some motivation to become slightly better organized.
 163
 164    Therefore, try and write the documentation so that it is relevant
 165    to, and can be read by such a diverse audience.
 166
 167 # Local variables:
 168 # mode: org
 169 # ispell-local-dictionary: "en_US-w_accents"
 170 # ispell-local-pdict: "./.aspell.org.pws"
 171 # End: