Add style guide

README.rst

@@ -9,6 +9,8 @@ The `documentation Wiki <https://github.com/owncloud/documentation/wiki>`_ is
 available for tips, tricks, edge cases, and anyone who wants to contribute more 
 easily, without having to learn Git and Sphinx.
 
+See :doc:`style_guide` for formatting and style conventions.
+
 Manuals
 -------
 

style_guide.rst

@@ -0,0 +1,99 @@
+============================
+ownCloud Manuals Style Guide
+============================
+
+*This is a work in progress*
+
+See `reStructuredText Primer <http://sphinx-doc.org/rest.html>`_ for a complete 
+Sphinx/RST markup reference.
+
+This is the official style guide for the ownCloud Administration and User 
+manuals. Please follow these conventions for consistency, and easier 
+proofreading and copyediting.
+
+When you are writing your text, make it as literal and specific as possible. Put 
+yourself in the place of the person who is using ownCloud and looking for 
+instructions on performing a task. Don't make them guess, but spell 
+out every step in order, and tell exactly what buttons to click or what form 
+fields to fill out. Give complete information; for example, when configuring a 
+timeout value be sure to say if it is in seconds or some other value. Say 
+``config.php`` rather than "the configuration file". When you are describing 
+features of a GUI administration form use the exact literal names of buttons, 
+form fields, and menus. Specify if menus are dropdown, right-click, 
+left-click, or mouseover.
+
+Page Filenames
+--------------
+
+Use lowercase filenames with underscores, for example file_name_config.rst.
+
+Page Titles and Headings
+------------------------
+
+There are many ways to markup headings and subheadings. This is the official 
+ownCloud way. Three levels is enough; if you find that you want more, 
+then re-think the organization of your text.
+
+==============
+Page title, h1
+==============
+
+Subhead, h2
+-----------
+
+Subhead, h3
+^^^^^^^^^^^
+
+Labels and Code
+---------------
+
+Elements in a GUI configuration form are in bold, and should be described as 
+literally as possible, so that your description matches what your reader sees 
+on the screen. For example, on the User listing page describe the various 
+elements like these examples::
+
+ **Username** field
+ **Password** field
+ **Groups** dropdown menu
+ **Create** button
+ ** Full Name** field
+ **Quota** dropdown menu
+
+.. figure:: users-files.png
+   :alt: User listings and administration page.
+   
+   Figure 1: The ownCloud user listing and administration page.
+   
+Use double-backticks for inline code and command examples::
+  
+  ``sudo -u www-data php occ files:scan --help``
+  ``maintenance:install``
+  
+When you are giving hyperlinks as examples, use double-backticks rather than 
+creating a live hyperlink::
+
+ ``https://example.com``
+
+Images
+------
+
+Images should be in .png format. Keep your screenshots focused on the items you 
+are describing. When you need an image of something large like a configuration 
+form on the ownCloud admin page, narrow your Web browser to fold the fields 
+into a smaller space, because a long skinny graphic is not very readable. Think 
+square.
+
+All images must have alt tags, which are brief and descriptive, and figure 
+numbers. Sphinx RST markup does not have a tag for figure numbers, so you must 
+use the caption element. You may use simple numbering like "Figure 1, Figure 2", 
+or add a caption. Captions must follow a blank line, like this example::
+
+  .. figure:: images/users-files.png
+     :alt: Files page showing the user's files.
+     
+     Figure 4: Files page showing the user's files.
+
+Images must go into a sub-directory of the directory containing your manual 
+page. Currently the manuals have both a single master images directory, and 
+image directories local to each chapter. A single master images directory is 
+difficult to maintain and inevitably becomes cluttered with obsolete images.