Merge pull request #3498 from stsewd/update-docs

Update docs

Author: ericholscher

docs/builds.rst

@@ -37,10 +37,8 @@ We will look inside a ``doc`` or ``docs`` directory first,
 and then look within your entire project.
 
 Then Sphinx will build any files with an ``.rst`` extension.
-If you have a ``README.rst``,
-it will be transformed into an ``index.rst`` automatically.
 
-Mkdocs
+MkDocs
 ~~~~~~
 
 When you choose *Mkdocs* as your *Documentation Type*,
@@ -50,10 +48,8 @@ we will generate one for you.
 We will look inside a ``doc`` or ``docs`` directory first,
 and then default to the top-level of your documentation.
 
-Then Mkdocs will build any files with an ``.md`` extension.
-If you have a ``README.md``,
-it will be transformed into an ``index.md`` automatically.
-As MkDocs doesn't support automatic PDF generation,
+Then MkDocs will build any files with a ``.md`` extension.
+As MkDocs doesn't support automatic PDF generation, 
 Read the Docs cannot create a PDF version of your documentation with the *Mkdocs* option.
 
 Understanding what's going on

docs/docs.rst

@@ -10,4 +10,30 @@ You can build the docs by installing ``Sphinx`` and running::
 	# in the docs directory
 	make html
 
-Let us know if you have any questions or want to contribute to the documentation.
+Please follow these guidelines when updating our docs.
+Let us know if you have any questions or something isn't clear.
+
+The brand
+---------
+
+We are called **Read the Docs**.
+The *the* is not capitalized.
+
+We do however use the acronym **RTD**.
+
+Titles
+------
+
+For page titles, or Heading1 as they are sometimes called, we use title-case.
+
+If the page includes multiple sub-headings (H2, H3),
+we usually use sentence-case unless the titles include terminology that is supposed to be capitalized.
+
+Content
+-------
+
+* Do not break the content across multiple lines at 80 characters,
+  but rather break them on semantic meaning (e.g. periods or commas).
+  Read more about this `here <http://rhodesmill.org/brandon/2012/one-sentence-per-line/>`_.
+* If you are cross-referencing to a different page within our website,
+  use the ``doc`` directive and not a hyperlink.

docs/faq.rst

@@ -23,7 +23,7 @@ as it `breaks the internet <http://www.w3.org/Provider/Style/URI.html>`_.
 Help, my build passed but my documentation page is 404 Not Found!
 -----------------------------------------------------------------
 
-This often happens becuase you don't have an `index.html` file being generated.
+This often happens because you don't have an `index.html` file being generated.
 Make sure you have one of the following files:
 
     * `index.rst`
@@ -57,7 +57,7 @@ environment, and will be set to ``True`` when building on RTD::
     {% endif %}
 
 I get import errors on libraries that depend on C modules
-----------------------------------------------------------
+---------------------------------------------------------
 
 .. note::
     Another use case for this is when you have a module with a C extension.

docs/install.rst

@@ -1,7 +1,7 @@
 .. _installing-read-the-docs:
 
 Installation
-=============
+============
 
 Here is a step by step plan on how to install Read the Docs.
 It will get you to a point of having a local running instance.
@@ -144,34 +144,18 @@ While the webserver is running, you can build documentation for the latest versi
 a project called 'pip' with the ``update_repos`` command.  You can replace 'pip'
 with the name of any added project::
 
-   python manage.py update_repos pip
+    python manage.py update_repos pip
 
 What's available
 ----------------
 
 After registering with the site (or creating yourself a superuser account),
 you will be able to log in and view the `dashboard <http://localhost:8000/dashboard/>`_.
 
-From the dashboard you can import your existing
-docs provided that they are in a git or mercurial repo.
+Importing your docs
+^^^^^^^^^^^^^^^^^^^
 
-
-Creating new Docs
-^^^^^^^^^^^^^^^^^
-
-One of the goals of `readthedocs.org <http://readthedocs.org>`_ is to make it
-easy for any open source developer to get high quality hosted docs with great
-visibility!  We provide a simple editor and two sample pages whenever
-a new project is created.  From there its up to you to fill in the gaps - we'll
-build the docs, give you access to history on every revision of your files,
-and we plan on adding more features in the weeks and months to come.
-
-
-Importing existing docs
-^^^^^^^^^^^^^^^^^^^^^^^
-
-The other side of `readthedocs.org <http://readthedocs.org>`_ is hosting the
-docs you've already built.  Simply provide us with the clone URL to your repo,
-we'll pull your code, extract your docs, and build them!  We make available
-a post-commit webhook that can be configured to update the docs on our site
-whenever you commit to your repo, effectively letting you 'set it and forget it'.
+One of the goals of readthedocs.org is to make it easy for any open source developer to get high quality hosted docs with great visibility!
+Simply provide us with the clone URL to your repo, we'll pull your code, extract your docs, and build them!
+We make available a post-commit webhook that can be configured to update the docs whenever you commit to your repo.
+See our :doc:`getting_started` page to learn more.