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 ^:t *: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 that
  15 end significant effort has been made and continues to be made by the Org
  16 community to ensure that high quality, user focused, documentation is
  17 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.  This
  22 guide, [[info:org:Top][The Org Manual]], concentrates on the facts of working with the
  23 system. Supplementing this, the [[Org web pages]] contain pointers to many
  24 tutorials and how-to's which capture much of spirit and imagination
  25 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 by
  34 others when making their own contributions.
  35
  36 * Org - 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" when
  52    referring to something unique to that feature.  It maybe, for example,
  53    a command is only available when you are actually editing a file using
  54    just that mode, add-on package or plug-in.
  55
  56  - Prefer "Org mode" to "Org-mode" or "org-mode". This is simply because
  57    it reflects an existing convention in [[info:emacs:Top][The Emacs Manual]] which
  58    consistently documents mode names in this form - "Text mode", "Outline
  59    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 use
  63    of some part of Org to edit it properly.
  64
  65  - Org uses "org-..." to ring fence a name space for itself in the Emacs
  66    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 I
  73 have made them up of course).
  74
  75  - Org has *lots* of commands and a /lot/ of them take prefix arguments
  76    of 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 authors
  82    and maintainers write them.  So it should be (I think) BBDB, MH-E,
  83    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 (eg ARCHIVE) are written in
  88    uppercase.  User defined tags (eg boss, home) are written in
  89    lowercase.
  90
  91  - Built-in properties (eg PRIORITY) are written in uppercase.  User defined
  92    properties (eg Release) are written in lowercase.
  93
  94  - [[info:org:Top][The Org Manual]] uses the @chapter, @section and @subsection Texinfo
  95    commands for sectioning.  I have tried to capitalize significant words
  96    in @chapter headings.  In @section and @subsection headings, just the
  97    first word is capitalized and all other words are lowercase (with
  98    exceptions of course...).  Thus, use:
  99
 100    @chapter Properties and Columns
 101
 102    @section Visibility cycling
 103
 104    *but*
 105
 106    @section Fast access to TODO states
 107
 108 * Miscellaneous
 109
 110  - Only two of the standard Texinfo indexes are used; those for concepts
 111    and keys.  This has some implications:
 112
 113    + The preference is to document commands by key rather than by name
 114
 115    + Texinfo commands such as @var and @defoption are not used.  The
 116      preference for this type of thing is that the user browses the
 117      customize groups.  If you want or need to refer to, say, a variable
 118      then document it as "the variable @code{org-startup-folded}"
 119
 120    + Entries in the concept index are normally all lower case unless
 121      some other rule dictates otherwise.
 122
 123  - Org documentation is written in American English, which is somewhat
 124    foreign as far as I am concerned, but live with it anyway.
 125
 126  - Org uses a number of compound words, words that I wouldn't necessarily
 127    run together.  Instead of worrying about whether these should be
 128    separate, hyphenated or compound I have simply gone with the majority
 129    case as originally written and then tried to make sure the spell
 130    checker knows what this chosen standard should be so that I do not
 131    worry about it anymore.
 132
 133  - I have run a spell checker periodically. Aspell works well and has a
 134    useful Texinfo filter (although, annoyingly, I cannot make this work
 135    with ispell.el and so I run it from the command line).  I have an Org
 136    specific Aspell configuration file (which sets an American dictionary,
 137    rules for compound words etc) and which, along with the associated
 138    word and replacement files, captures some of the more detailed and
 139    somewhat arbitrary rules I have used.
 140
 141  - Org has really low entry barriers.  The requirements seem simply
 142    to be:
 143
 144    + You can use Text mode or, pretty much, any derivative of it
 145
 146    + You have some motivation to become slightly better organized.
 147
 148    Therefore, try and write the documentation so that it is relevant to,
 149    and can be read by such a diverse audience.
 150
 151 # Local variables:
 152 # mode: org
 153 # fill-column: 72
 154 # ispell-local-dictionary: "en_US-w_accents"
 155 # ispell-local-pdict: "./.aspell.org.pws"
 156 # End: