Consistency across documentation is very important. Therefore we have some rules. ### The style guide follows the [Internal Oxford University Style Guide](https://www.ox.ac.uk/sites/files/oxford/media_wysiwyg/University%20of%20Oxford%20Style%20Guide.pdf) This version is also available [New Hart's Rules](http://www.amazon.co.uk/New-Harts-Rules-Oxford-Guides/dp/0199570027/ref=dp_ob_title_bk) (28 Aug 2014) and is more comprehensive. However you should note the below. Oxford University Press, in all of its publications, prefers to use the –ize suffix - this is true for its dictionaries and grammar guides as well as for its other publications. However, at the University of Oxford they prefer the –ise spelling as more reflective of modern English, so they recommend using that spelling in their publications. Which brings us on to the next point. ### Documentation is to be consistently written in Post 1776 "Franco-British" (Modern British spelling) we use ...ise rather than '...ize' - hence, recognise and not 'recognize'; specialise and not 'specialize'. It is also our style not to use 'x' in the middle of a word where there is an alternative spelling of 'ct' - hence, inflection - and not 'inflexion'; reflection - and not 'reflexion'; connection - and not 'connexion' etc Some More examples `organisation` not ~~`organization`~~ `colour` not ~~`color`~~ except for code snippets. ``` .class { color :blue; } ``` This is obviously due to the fact that the Franco-English spelling of the word would just not work when run in the browser. We also use a few more defined spellings across the documentation such as **queuing** rather than **queueing** > Would you like to argue about this and possibly descend into a knife fight? email hello@maxmckenzie.uk ## Arrangement Each section of the documentation should be named as per the service it describes. for example the `JavaScript SDK` within each of these sections. The following sub sections should be defined in this order. Not all are necessary and you can drop ones that are not appropriate. - **Index** This is the main landing page of each section which provides background information on the particulars of the service we are describing. - **Installation Instructions (Install)** This is where we give step by step instructions on how to install the necessary dependencies and code needed to implement the service. - **Getting Started** Once installed this section defines what can be done next. - **Components and Snippets** Useful snippets of code and examples of how to expand said code can be defined in here. It does not need to be 100% comprehensive of the service. It serves as a way to get the reader to become familiar with the syntax. - **Demo's** If possible working demo's examples of implementations should be freely available on Github. This will help people to understand the implementation and in some cases use the examples in there own code base. - **API Reference and Tools** Complete Self Generating References should be included here. As well as any useful tools such as debug tools CLI tools and JSFiddle like tools. - **Use Cases** This was going to be its own section. However it's more appropriate within the section that the use case describes. Therefore it should be included as a sub section. ## Emphasis The documentation is written in [Github Flavoured Markdown](https://help.github.com/categories/writing-on-github/). Warnings and useful tips should be wrapped in a blockqoute. ``` > This is an important note! ``` Important sections should be higher in the arrangement. As with the structure of our sub sections. Install comes before Getting Started. This is the case with the main sections of the documentation. The JavaScript SDK is more widely used than the API. Thus it comes first. Order is defined by pre-pending `01_` or `02` and so on. Additionally you should give lists a bold tag at the start this makes it easy to distinguish. - **list items** are easy to read when in bold - **list items** are easy to read when in bold - **list items** are easy to read when in bold - list items are harder to read when not in bold - list items are harder to read when not in bold - list items are harder to read when not in bold There is again a context where this is appropriate and a context where it is not appropriate. For example at the top of this document we have not used bold in the list items as each one is a description of an action not a list of things. ## Clarity It is important that none of our content or language creates simultaneous conflicting reactions from the reader. So your opinion about a particular implementation of a service, or the fact that a dependency is necessary yet you do not like it. Should never be mentioned. > See 'Tone' below for more information - **Font Rules and testing** 1Iil <- if these characters all look the same then you've chosen a poor font. as in fact they are the number one, a capital I (eye) and a lower case i (eye), and a lower case l (el). - **Graphs** should be simple and easy to understand. ## Tone As with most technical documentation you should try to devolve your self from it in terms of personality. This keeps the tone of the documentation formal and professional. > "Newspaper reporters and technical writers are trained to reveal almost nothing about themselves in their writing. This makes them freaks in the world of writers, since almost all of the other ink-stained wretches in that world reveal a lot about themselves to the reader." - [Kurt Vonnegut](http://peterstekel.com/PDF-HTML/Kurt%20Vonnegut%20advice%20to%20writers.htm) However there is a limit on how far this needs to go. 'You should use this snippet' does not need to be. 'One should use this snippet' ## Ethos Check spelling constantly. Make sure you ad-hear to the style guide we have defined here. The documentation should be as error free as possible. This gives the visual language credibility. Additionally this should also be the case with code samples. If any updates are done to any of the syntax they should be reflected in the documentation as soon as possible to avoid out of date snippets of code.