[Pkg-owncloud-commits] [owncloud-doc] 05/09: update repo readme

[David Prévot]

This is an automated email from the git hooks/post-receive script.

taffit pushed a commit to branch master
in repository owncloud-doc.

commit 9b5b3bd19a7f95ffae1d75ab517b9f6255cacdda
Author: Carla Schroder <carla at owncloud.com>
Date:   Fri Sep 11 11:41:50 2015 -0700

    update repo readme
    
    Conflicts:
    	README.rst
    
    Conflicts:
    	CONTRIBUTING.rst
    	README.rst
---
 README.rst | 66 +++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 37 insertions(+), 29 deletions(-)

diff --git a/README.rst b/README.rst
index c6bbfc4..ef4d5b1 100644
--- a/README.rst
+++ b/README.rst
@@ -2,32 +2,36 @@
 ownCloud Documentation
 ======================
 
-This is the ownCloud documentation. It currently focuses on the server,
-client manuals are in the respective git repositories. Because of the
-complexity of the server and the split into the core and apps modules,
-the manuals are in this separate directory.
+Documentation is published on `<https://doc.owncloud.org>`_ and 
+`<https://doc.owncloud.com.>`_
 
-Documentation is published on https://doc.owncloud.org and https://doc.owncloud.com.
-
-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 using Git and Sphinx.
+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.
 
 Manuals
 -------
 
-At this point, this repository hosts three manuals:
+This repository hosts three manuals:
 
-* **Users Manual:** Covers topics from an end user's Point of View
-* **Administrators Manual:** Setup, Deployment, Best Practices, etc.
-* **Developers Manual:** Developing Apps for ownCloud & understanding the
-  core Architecture.
+* **Users' Manual**
+* **Administration Manual**
+* **Developers Manual** 
   
 Please work in the appropriate branch. stable6 is for ownCloud 6, stable7 is for ownCloud 7, and stable8 is 8.0, stable8.1 is 8.1, and master is version 8.2.
 
 Please wrap lines at 80 characters.
 
 .. note:: ``configuration_server/config_sample_php_parameters.rst`` is auto-generated from the core
-   config.sample.php file; changes to this file must be made in core 
-   `<https://github.com/owncloud/core/tree/master/config>`_
+   config.sample.php file; changes to this file must be made in core `<https://github.com/owncloud/core/tree/master/config>`_
+
+Spelling and Capitalization Conventions
+---------------------------------------
+
+As this grows it may be moved to its own page.
+
+* ownCloud Apps Store
+* synchronize
 
 License
 -------
@@ -38,27 +42,33 @@ Attribution 3.0 Unported license (`CC BY 3.0`_).
 .. _CC BY 3.0: http://creativecommons.org/licenses/by/3.0/deed.en_US
 
 Style
--------
+-----
 
 It is using the `Sphinx Documentation Generator
 <http://sphinx.pocoo.org/>`_. The syntax follows the `reStructuredText
 <http://docutils.sourceforge.net/rst.html>`_ style, and can also be edited
 from GitHub.
 
-For PHP documentation you'll need to get the according language
-domain package. The documenation for PHP source is located at
-http://packages.python.org/sphinxcontrib-phpdomain/reference.html
-
 Editing
 -------
-Contributing to the documentation requires a github account.
 
-To edit a document, either do a checkout of the repository and edit the rst
-files from there, or work directly on github. The latter is only really
-suitable for small fixes and improvements because substantial editing efforts
-can better be controlled in an editor.
+Contributing to the documentation requires a Github account. Make sure you are 
+working in the correct branch for your version of ownCloud or client apps. 
+If your edits pertain to multiple manual versions, be prepared to backport as 
+needed.
 
-To edit on github, fork the repository (see top-right of the screen, under
+To edit a document, you can edit the .rst files on your local system, or work 
+directly on Github. The latter is only suitable for small fixes and improvements 
+because substantial editing efforts can better be controlled on your local PC. 
+
+The best way is to install a complete Sphinx build environment and work on your 
+local PC. You will be able to make your own local builds, which is the fastest 
+and best way to preview for errors. Sphinx will report syntax errors, missing 
+images, and formatting errors. The Github preview is not complete and misses 
+many mistakes. Create a new branch against the master or stable branch you are 
+editing, make your edits, then push your new branch to Github and open a new PR. 
+
+To edit on Github, fork the repository (see top-right of the screen, under
 your username). You will then be able to make changes easily. Once done, 
 you can create a pull request and get the changes reviewed and back into
 the official repository.
@@ -153,7 +163,7 @@ Sometimes, existing documentation might be in Word or LibreOffice documents. To
 make it part of this documentation collection, follow these steps:
 
 Prerequisites
-^^^^^^^^^^^^
+^^^^^^^^^^^^^
 
 1. Install Python 2.x
 2. Install odt2sphinx (``easy_install odt2sphinx``)
@@ -168,6 +178,4 @@ Process
 4. Wrap text lines at 80 chars, apply markup fixes
 
 .. _CC BY 3.0: http://creativecommons.org/licenses/by/3.0/deed.en_US
-.. _`Xcode command line tools`: 
-http://stackoverflow.com/questions/9329243/xcode-4-4-and-later-install-command-
-line-tools
+.. _`Xcode command line tools`:http://stackoverflow.com/questions/9329243/xcode-4-4-and-later-install-command-line-tools

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/owncloud-doc.git