Documentation_Standards.org (7642B)
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 * org-manual.org specific conventions 98 99 Org git repository comes with an .org version of the manual in the 100 =doc/= 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 - Prefer inline footnote definition when a footnote consists of a 116 single sentence. 117 118 - Internal links to headlines always start with a star. 119 120 - Tags, node properties, are not shown with the surrounding colons. 121 122 - When to use = ... = or ~ ... ~ markup: 123 124 + files or extensions use = ... =, 125 + anything that is meant to be written in the Org buffer uses = ... =, 126 + any meaningful token in a programming language uses ~ ... ~. 127 128 * Miscellaneous 129 130 - Only two of the standard Texinfo indexes are used; those for 131 concepts and keys. This has some implications: 132 133 + The preference is to document commands by key rather than by name 134 135 + Texinfo commands such as @var and @defoption are not used. The 136 preference for this type of thing is that the user browses the 137 customize groups. If you want or need to refer to, say, a 138 variable then document it as "the variable 139 @code{org-startup-folded}" 140 141 + Entries in the concept index are normally all lower case unless 142 some other rule dictates otherwise. 143 144 - Org documentation is written in American English, which is somewhat 145 foreign as far as I am concerned, but live with it anyway. 146 147 - Org uses a number of compound words, words that I wouldn't 148 necessarily run together. Instead of worrying about whether these 149 should be separate, hyphenated or compound I have simply gone with 150 the majority case as originally written and then tried to make sure 151 the spell checker knows what this chosen standard should be so that 152 I do not worry about it anymore. 153 154 - I have run a spell checker periodically. Aspell works well and has 155 a useful Texinfo filter (although, annoyingly, I cannot make this 156 work with ispell.el and so I run it from the command line). I have 157 an Org specific Aspell configuration file (which sets an American 158 dictionary, rules for compound words etc) and which, along with the 159 associated word and replacement files, captures some of the more 160 detailed and somewhat arbitrary rules I have used. 161 162 - Org has really low entry barriers. Requirements seem simply to be: 163 164 + You can use Text mode or, pretty much, any derivative of it 165 + You have some motivation to become slightly better organized. 166 167 Therefore, try and write the documentation so that it is relevant 168 to, and can be read by such a diverse audience. 169 170 # Local variables: 171 # mode: org 172 # ispell-local-dictionary: "en_US-w_accents" 173 # ispell-local-pdict: "./.aspell.org.pws" 174 # End: