Ideally, all AROS documentation should share a common style, regardless of the intended audience of a specific document. While first-time contributors can't be expected to adhere closely to the style in use, all documentation should eventually be made to implement a single style.
This document lists a number of guidelines for our documentation, both in text form and for the web site. To the new contributor they should give an overview of issues that could influence the style of his text; for those regularly involved with documentation and translation they should provide a mould that documents could be formed with. Hopefully, it will in time grow to be a full-fledged style guide for AROS documents.
This document focusses on the English language versions of the documentation, as that language is used as the AROS default. It's expected that eventually translators for other languages not just translate this document, but substitute and add language-specific guidelines that suit the needs for their language.
We have to take care to create documentation that can, in it's text form, easily be read by all who work on it. This influences the characters we can use, until AROS gets Unicode-support, as well as the text width used.
Our English language web-pages are encoded as ISO 8859-15. It'll probably make life easier all around if you set your editor to that same set when working on English documentation, if possible. Of course, if you have no need for characters beyond the ASCII set, any ISO 8859 set will likely suffice, just don't forget that limitation. For other languages, the same will holds, though in some cases with a different character set.
Several characters are available that could be used as apostrophes in our texts. To avoid a chaos of apostrophes, we've settled on using the ' (decimal ASCII code 39) only. Other possibilities, like accents, tend to be asymmetrical, which doesn't work well for punctuation that should hang in between two letters. Don't use those.
On the other hand, ReST uses back ticks for a number of purposes. Do not confuse the two.
If you use a word processor, rather than a text editor, check that it doesn't change the apostrophes automatically to accents or non-supported characters. Also, take care not to use asymmetrical aligned quotes as apostrophes.
Tabs, tabulator stops, do have some functions in text, but can also cause problems.
Ideally, the spelling of each new document and each revision would be correct to begin with, and most contributors will have spell checkers to help make that a reality. Perfection is hard to come by, however, and we should expect corrections made to the language of documents. In this case, differences of opinion are possible about what is correct.
With people from different locations contributing, it's nigh-unavoidable that different dialects of the same language will be used in the same document. At least where spelling is concerned, try to adhere to the spelling that was used when the document was created or, when viewing just the current document, the spelling that most of the document adheres to.
Language corrections should ideally be done separately from content changes, but we shouldn't be too religious about that. Writers who disagree with language corrections are advised to take the matter up with the person who made that correction, rather than start commit wars.
Each language will have its own problems with pronouns; the issues addressed here are those stemming from the fact that AROS is created by a collective, and those stemming from the multiple meanings of "you" in English and its equivalents in other languages.
"I" is the 9th letter of the alphabet. As a pronoun it can't be used in a document, as that would be the document itself speaking. The writers of each document are supposed to be the AROS Team, and they, as a collective can't refer to themselves as "I". There are a few exceptions to this, like a draft a or a commentary, as the assumption there is that the writer himself addresses the reader. Note, however, that after a draft has been revised a few times by other contributors, this quickly becomes impractical.
"You" is the reader, when the reader is supposed to follow steps. In other contexts it's usually unnecessary to address the reader directly. Especially try to avoid inventing facts about "you", as in: "You as a tester won't know this implementation detail:". The same message can usually written without excluding part of the audience: "If you're a tester, you might not know this implementation detail:" or simply "This is an implementation detail testers might not know:".
"We" is the "AROS (Development/Documentation/Testing) Team", as appropriate. It does not refer to "You and I" (see "I" and "You", above). Writers who like to take the reader by the hand will find that this can also be done in ways that are less confusing, and easier on the reader.
"He" is the user/reader etc., referred to in the third person. We can jump high and low, but our users and readers are most likely male, and it's a simple choice to just accept that as our single third person reference, rather than having to take care to use "she", "(s)he", "they" in the singular, "she/he", etc. consistently.
Often, there's no reason to use a pronoun at all, but don't artificially write about "the user" five times in a row.
"It" can be many things. (Well, one thing at a time.) This makes it easy to use for avoiding reusing the same term over and over, but do take care that the reference is a clear one. "I laid my hat next to the cushion and sat down on it" is not the kind of structure you would like use while trying to explain some intricate AROS detail. The same holds for "this", "that", "these", "there", and a few more words of a similar nature, that all may or may not refer to what you intended to write about.
Don't use jargon abbreviations like "abbrevs", "apps", "dirs", "docs", and "params" unless they happen to be names of directories or similar. For now, we'll assume our documents will only exist in digital form, hence writing out a few words more is not going to bloat the book on your desk. Using common abbreviations from the field you're treating is o.k., but do write them out in parentheses the first time you use them. Using common abbreviations from the language in general is acceptable, if you do remember that they tend to use dots: e.g., i.e., etc., and a few more like them. Try to avoid using those at the end of the sentence, as the skipping of the full stop in those cases tends can be confusing.
If you use a term which you expect to be unknown to a considerable part of the readers, give a short description as part of the introduction. If possible, link to a page that treats the subject in more detail, and if not, remember there's always the glossary. At least:
There are quite a few terms in this project that either have specific meanings in their field or are Amiga- or AROS-specific. It would be a good thing to build a glossary for such words, giving short explanations and, where possible, linking to pages where more information can be found.
Names in the AROS-DOS file system are case-insensitive. This allows the user to write them with any capitalisation he chooses. That doesn't mean, however, that we ourselves can take that freedom and write "DEVS:", "Devs:", "devs:" and maybe even "dEvS:" as we see fit. We should stick to a single pattern as well as we can.
These are names, of files, directories and devices, and they should get a leading capital; current practice appears to be that each word gets such a leading capital, if necessary ignoring that spaces have been omitted from the name. However, if part of the name is text that would normally be written entirely in capitals, then it's written that way in these cases as well. E.g. "Assign", "Libs:", "AddDataTypes", but "AROSMonDrvs".
In a number of cases, however, the case is fixed, probably because the names are passed though case-sensitive Exec. These cases should be documented, together with their general patterns and exceptions to those.
Some names and abbreviations are so familiar to us that we sometimes forget that they are not ordinary words. Other words apparently seem so special that we create abbreviations or capitalisations. As the mixed spelling this causes is rather confusing for the reader, we should try to limit ourselves to writing such words in only one way. An exception are the occurrences in filenames etc., where other conventions govern the way names are written.
Try to write the following words written out like this and/or using this capitalisation:
Language being rather organic, the way compounds are written can rarely be described with fixed rules. The Amiga User's Guide - AmigaDOS (1992), uses "file system", but "filename". Though we may be able to use sources like that to determine whether a space or hyphen should be used or not, and whether the word should have one or more capitals, the only way to do so consistently would be to create a compounds list, adding to it as we determine the way these should be written.
In some cases, it's necessary to pay special attention to the exact way to represent text, to avoid possible confusion.
In cases where the contents of a quote have to be copied verbatim, counter to English usage do not include trailing punctuation (full stops, question marks, etc.) inside the quotes, but let them trail behind:
Type in the shell "MakeDir Ram:Test".
In other cases, the convention does apply. Likewise, other languages should follow the conventions for quoting in those languages, except where they would cause problems with the purpose of the quotes.
Object names, be they function names, method names, etc., are used throughout the documentation. Some of those names start with a lower-case letter or with punctuation, which is rather confusing at the start of the sentence, as only upper-case letters are expected there. In such cases, and wherever it's unclear what type of object you're talking about, add the type in front of it: "The macro __small__ ...".
By using ReST to represent our texts, we give ourselves plenty of rope regarding sections and headings. This is also plenty of rope to hang ourselves. Some constraints on the amount and type of headings, and the characters they are indicated with, would be a good thing.
ReST allows gathering the headings of a document in a table of content. For a document of non-trivial length such a table should be added, near the top of the document. In the location where you would want the table of content to appear, add a line with the ReST directive ".. Contents::". Normally, no title is specified for the table: this guarantees the default title for tables of content, together with its translation into each language, is used throughout the documentation.
A page should not need more than four types of headings: One for the page title, and three for main sections, sections and subsections. More levels of sectioning usually means the document is too specific in the parts where extra sectioning is used; try to split off the details to a details page. If there is a really good reason to use more levels, at least limit the depth of the table of contents, so it won't jump all over the place. This is done by adding " :depth: 3" on the line below the contents directive. This can also be used, with a lower depth, when a document includes a large number of small subsections, e.g. a library documentation, including for each function the same group of documentation fields.
Headings, other than page titles, get letters in upper-case like a sentence would. Taking care of hierarchical style differences is the domain of the generation scripts; it's not done by writing a heading completely in capitals.
Headings are a form of title. As with all titles, they do not end in punctuation other than question or exclamation marks, and then only when there is a very good reason for them.
Separators without text, transitions, have less indication of their function than headings. It's therefore preferable to give them the same look throughout the text.
To allow referring to text further away than in the next or previous paragraph, we need terms for the different types of heading with the content following them. Such names may also create a bit more uniformity in the amount of information included in such a section. Where several file combine into a larger document, these files too will need such a term, and that larger document may group files together into even larger units.
A clear representation of the text has no direct influence on the resulting page, but it should improve readability for those working on the documentation.
In the text, skipping single lines is used as separation. Separating sections will therefore require at least two skipped lines to make the separation stand out. Below the heading, skip one line to make the heading stand out from the content below it.
Allow the text some space; put a newline character at the end of the document, so there will be one empty line at the end in most readers. This give paragraphs a consistent look, always ending in an empty line.
Autodocs have some style issues that are particular to those documents, which are described in documentation/developers/documenting.en. Apart from those, their style should follow this style guide.
As autodocs support just a single language, the current assumptions are that all source code contributed to AROS is in English, and that all developers have a reading skill in English. This suffices for system development. A complete AROS documentation, on the other hand, would include documentation written in each supported language.
Normally, all documents are translated from English, with the consequence that this section is rather small, here. For other languages it's likely to contain more guidelines on e.g. deciding whether a term should be translated or borrowed.
Steps to take after publication of this document, not necessarily in this order: