Add documentation guidelines

docs/contributing/docs.rst

@@ -0,0 +1,231 @@
+=====================
+Writing documentation
+=====================
+
+.. note::
+
+   Heavily inspired by the
+   `django project's guidelines <https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/>`_
+
+We place a high importance on consistency, readability and completeness of documentation.
+If a feature is not documented, it does not exist. If a behavior is not documented,
+it is a bug! We try to treat our
+documentation like we treat our code: we aim to improve it as often as
+possible.
+
+Documentation changes generally come in two forms:
+
+* General improvements: typo corrections, error fixes and better
+  explanations through clearer writing and more examples.
+
+* New features: documentation of features that have been added to the
+  framework since the last release.
+
+This section explains how writers can craft their documentation changes
+in the most useful and least error-prone ways.
+
+Getting the raw documentation
+=============================
+
+Though TLJH's documentation is intended to be read as HTML at
+https://the-littlest-jupyterhub.readthedocs.io/, we edit it as a collection of text files for
+maximum flexibility. These files live in the top-level ``docs/`` directory of
+TLJH's repository.
+
+If you'd like to start contributing to our docs, get the development version of
+TLJH from the source code repository. The development version has the
+latest-and-greatest documentation, just as it has latest-and-greatest code.
+
+Getting started with Sphinx
+===========================
+
+TLJH's documentation uses the Sphinx__ documentation system, which in turn
+is based on docutils__. The basic idea is that lightly-formatted plain-text
+documentation is transformed into HTML, PDF, and any other output format.
+
+__ http://sphinx-doc.org/
+__ http://docutils.sourceforge.net/
+
+To build the documentation locally, install Sphinx:
+
+.. console::
+
+     $ pip install Sphinx
+
+Then from the ``docs`` directory, build the HTML:
+
+.. console::
+
+     $ make html
+
+To get started contributing, you'll want to read the :ref:`reStructuredText
+reference <sphinx:rst-index>`.
+
+Your locally-built documentation will be themed differently than the
+documentation at `the-littlest-jupyterhub.readthedocs.io <https://the-littlest-jupyterhub.readthedocs.io>`_.
+This is OK! If your changes look good on your local machine, they'll look good
+on the website.
+
+How the documentation is organized
+==================================
+
+The documentation is organized into several categories:
+
+* **Tutorials** take the reader by the hand through a series
+  of steps to create something.
+
+  The important thing in a tutorial is to help the reader achieve something
+  useful, preferably as early as possible, in order to give them confidence.
+
+  Explain the nature of the problem we're solving, so that the reader
+  understands what we're trying to achieve. Don't feel that you need to begin
+  with explanations of how things work - what matters is what the reader does,
+  not what you explain. It can be helpful to refer back to what you've done and
+  explain afterwards.
+
+* **Topic guides** aim to explain a concept or subject at a
+  fairly high level.
+
+  Link to reference material rather than repeat it. Use examples and don't be
+  reluctant to explain things that seem very basic to you - it might be the
+  explanation someone else needs.
+
+  Providing background context helps a newcomer connect the topic to things
+  that they already know.
+
+* **Reference guides** contain technical reference for APIs.
+  They describe the functioning of TLJH's internal machinery and instruct in
+  its use.
+
+  Keep reference material tightly focused on the subject. Assume that the
+  reader already understands the basic concepts involved but needs to know or
+  be reminded of how TLJH does it.
+
+  Reference guides aren't the place for general explanation. If you find
+  yourself explaining basic concepts, you may want to move that material to a
+  topic guide.
+
+* **How-to guides** are recipes that take the reader through
+  steps in key subjects.
+
+  What matters most in a how-to guide is what a user wants to achieve.
+  A how-to should always be result-oriented rather than focused on internal
+  details of how TLJH implements whatever is being discussed.
+
+  These guides are more advanced than tutorials and assume some knowledge about
+  how TLJH works. Assume that the reader has followed the tutorials and don't
+  hesitate to refer the reader back to the appropriate tutorial rather than
+  repeat the same material.
+
+* **Troubleshooting guides** help reader answer the question "Why is my JupyterHub
+  not working?".
+
+  These guides help readers try find causes for their symptoms, and hopefully fix
+  the issues. Some of these need to be specific to cloud providers, and that is
+  acceptable.
+
+Writing style
+=============
+
+When using pronouns in reference to a hypothetical person, such as "a user with
+a running notebook", gender neutral pronouns (they/their/them) should be used.
+Instead of:
+
+* he or she... use they.
+* him or her... use them.
+* his or her... use their.
+* his or hers... use theirs.
+* himself or herself... use themselves.
+
+Commonly used terms
+===================
+
+Here are some style guidelines on commonly used terms throughout the
+documentation:
+
+* **TLJH** -- common abbreviation of The Littlest JupyterHub. Fully
+  capitalized except when used in code / the commandline.
+
+* **Python** -- when referring to the language, capitalize Python.
+
+* **Notebook Interface** -- generic term for referring to JupyterLab,
+  nteract, classic notebook & other user interfaces for accessing
+
+
+Guidelines for reStructuredText files
+=====================================
+
+These guidelines regulate the format of our reST (reStructuredText)
+documentation:
+
+* In section titles, capitalize only initial words and proper nouns.
+
+* Wrap the documentation at 120 characters wide, unless a code example
+  is significantly less readable when split over two lines, or for another
+  good reason.
+
+
+* Use these heading styles::
+
+    ===
+    One
+    ===
+
+    Two
+    ===
+
+    Three
+    -----
+
+    Four
+    ~~~~
+
+    Five
+    ^^^^
+
+Documenting new features
+========================
+
+Our policy for new features is:
+
+    All new features must have appropriate documentation before they
+    can be merged.
+
+Minimizing images
+=================
+
+Optimize image compression where possible. For PNG files, use OptiPNG and
+AdvanceCOMP's ``advpng``:
+
+.. code-block:: console
+
+   $ cd docs
+   $ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
+   $ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`
+
+This is based on OptiPNG version 0.7.5. Older versions may complain about the
+``--strip all`` option being lossy.
+
+Spelling check
+==============
+
+Before you commit your docs, it's a good idea to run the spelling checker.
+You'll need to install a couple packages first:
+
+* `pyenchant <https://pypi.org/project/pyenchant/>`_ (which requires
+  `enchant <https://www.abisource.com/projects/enchant/>`_)
+
+* `sphinxcontrib-spelling
+  <https://pypi.org/project/sphinxcontrib-spelling/>`_
+
+Then from the ``docs`` directory, run ``make spelling``. Wrong words (if any)
+along with the file and line number where they occur will be saved to
+``_build/spelling/output.txt``.
+
+If you encounter false-positives (error output that actually is correct), do
+one of the following:
+
+* Surround inline code or brand/technology names with grave accents (`).
+* Find synonyms that the spell checker recognizes.
+* If, and only if, you are sure the word you are using is correct - add it
+  to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).

docs/index.rst

@@ -52,4 +52,5 @@ to people contributing in various ways.
 .. toctree::
    :titlesonly:
 
+   contributing/docs
    contributing/dev-setup