diff --git a/README.rst b/README.rst index fd8e7348a..ec8181b90 100644 --- a/README.rst +++ b/README.rst @@ -9,6 +9,8 @@ The `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 ------- diff --git a/style_guide.rst b/style_guide.rst new file mode 100644 index 000000000..db2dff1f1 --- /dev/null +++ b/style_guide.rst @@ -0,0 +1,99 @@ +============================ +ownCloud Manuals Style Guide +============================ + +*This is a work in progress* + +See `reStructuredText Primer `_ 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. diff --git a/users-config.png b/users-config.png new file mode 100644 index 000000000..649aa7fff Binary files /dev/null and b/users-config.png differ