Refined content

docs/build/html/_sources/principles.rst.txt

@@ -2,156 +2,126 @@ Principles
 ==========
 
 
-Personas
---------
-
-Curious person
-~~~~~~~~~~~~~~
-
-Examples include:
-
-* Students
-* Professionals in industry
-
-
-Researcher
-~~~~~~~~~~
-
-Examples include:
-
-* Academic researchers
-* Tech leads in industry
-
-
-User
-~~~~
-
-TODO
-
-
-Contributor
-~~~~~~~~~~~
-
-TODO
-
-
-Platform maintainer
-~~~~~~~~~~~~~~~~~~~
-
-Examples include:
-
-* Coq Platform maintainers
-* Nix package maintainers
-
-
-Upstream maintainer
-~~~~~~~~~~~~~~~~~~~
-
-Examples include:
-
-* Coq maintainers
+Roles & personas
+----------------
+
+Many different roles & personas have an interest in project style.
+
+* Curious person
+   * Student
+   * Academic researcher
+   * Professional in industry
+* Researcher
+   * Academic researcher
+* User
+   * Student
+   * Academic researcher
+   * Professional in industry
+* Contributor
+   * Student
+   * Academic researcher
+   * Professional in industry
+* Platform maintainer
+   * `Coq Platform <https://github.com/coq/platform>`_ maintainers
+   * Nix package maintainers
+   * Academic researcher
+* Upstream maintainer
+   * Coq maintainers
+   * Academic researcher
+   * Professional in industry
 
 
 Use cases
 ---------
 
-Browsing the code (in a browser)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*Curious person, researcher, user, contributor*
-
-TODO
-
-
-
-Browsing the code (in a proof assistant)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*Curious person, researcher, user, contributor*
-
-TODO
-
-
-Isolating & resolving build issues
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*User, contributor, platform maintainer*
-
-TODO
-
-
-Exploring undocumented features
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*Researcher, user*
-
-TODO
-
-
-Understanding the architecture
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*Researcher, user, contributor*
-
-TODO
-
-
-Shipping new features
-~~~~~~~~~~~~~~~~~~~~~
-
-*Contributor*
-
-TODO
-
-
-Refactoring
-~~~~~~~~~~~
-
-*Contributor*
-
-TODO
-
+Project style impacts several frequent use cases.
+
+* Browsing the code (in a browser)
+   * Curious person
+   * Researcher
+   * User
+   * Contributor
+   * Platform maintainer
+   * Upstream maintainer
+* Browsing the code (in a proof assistant)
+   * Curious person
+   * Researcher
+   * User
+   * Contributor
+   * Platform maintainer
+   * Upstream maintainer
+* Isolating & resolving build issues
+   * User
+   * Contributor
+   * Platform maintainer
+   * Upstream maintainer
+* Exploring undocumented features
+   * Researcher
+   * User
+   * Contributor
+* Understanding the architecture
+   * Researcher
+   * User
+   * Contributor
+* Shipping new features
+   * Contributor
+* Refactoring
+   * Contributor
+   * Platform maintainer
+   * Upstream maintainer
+
+
+Desired outcome
+---------------
+
+This style guide seeks to drive the following outcomes:
 
-Objectives
-----------
 
 Mitigate bike-shedding
 ~~~~~~~~~~~~~~~~~~~~~~
 
-TODO
+* Shipping new features
+* Refactoring
 
 
 Style is enforcable by a linter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-TODO
+* Shipping new features
+* Refactoring
 
 
 Find & replace work as expected
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-TODO
+* Browsing the code (in a browser)
+* Browsing the code (in a proof assistant)
+* Isolating & resolving build issues
+* Exploring undocumented features
+* Understanding the architecture
+* Shipping new features
+* Refactoring
 
 
 Code is robust against changes to the Coq engine
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-TODO
+* Isolating & resolving build issues
 
 
 Code is minimally impacted by changes in upstream components
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-TODO
+* Isolating & resolving build issues
 
 
 Code changes have minimal impact on downstream users
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-TODO
+* Isolating & resolving build issues
 
 
 Upstream maintainers are not punished for offering to help
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-TODO
+* Isolating & resolving build issues

docs/build/html/_sources/project_structure.rst.txt

@@ -38,14 +38,13 @@ Dependencies
 Source control
 --------------
 
-Use :code:`git`.
-
+Use :command:`git`.
 
 *Rationale:*
 
-* :code:`git` is ubiquitous in the Coq ecosystem. It is well-known by all of the personas.
-* :code:`git` submodules are widely used in the Coq ecosystem. This is particularly true for bleeding-edge development. It is wise to be compatible with this practice.
-* :code:`git` works well with :code:`opam`.
+* :command:`git` is ubiquitous in the Coq ecosystem. It is well-known by all of the personas.
+* :command:`git` submodules are widely used in the Coq ecosystem. This is particularly true for bleeding-edge development. It is wise to be compatible with this practice.
+* :command:`git` works well with :code:`opam`.
 
 
 Continuous Integration

docs/build/html/index.html

@@ -40,26 +40,9 @@ <h2>Table of Contents<a class="headerlink" href="#table-of-contents" title="Perm
 <div class="toctree-wrapper compound">
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="principles.html">Principles</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="principles.html#personas">Personas</a><ul>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#curious-person">Curious person</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#researcher">Researcher</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#user">User</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#contributor">Contributor</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#platform-maintainer">Platform maintainer</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#upstream-maintainer">Upstream maintainer</a></li>
-</ul>
-</li>
-<li class="toctree-l2"><a class="reference internal" href="principles.html#use-cases">Use cases</a><ul>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#browsing-the-code-in-a-browser">Browsing the code (in a browser)</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#browsing-the-code-in-a-proof-assistant">Browsing the code (in a proof assistant)</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#isolating-resolving-build-issues">Isolating &amp; resolving build issues</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#exploring-undocumented-features">Exploring undocumented features</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#understanding-the-architecture">Understanding the architecture</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#shipping-new-features">Shipping new features</a></li>
-<li class="toctree-l3"><a class="reference internal" href="principles.html#refactoring">Refactoring</a></li>
-</ul>
-</li>
-<li class="toctree-l2"><a class="reference internal" href="principles.html#objectives">Objectives</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="principles.html#roles-personas">Roles &amp; personas</a></li>
+<li class="toctree-l2"><a class="reference internal" href="principles.html#use-cases">Use cases</a></li>
+<li class="toctree-l2"><a class="reference internal" href="principles.html#desired-outcome">Desired outcome</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="principles.html#mitigate-bike-shedding">Mitigate bike-shedding</a></li>
 <li class="toctree-l3"><a class="reference internal" href="principles.html#style-is-enforcable-by-a-linter">Style is enforcable by a linter</a></li>
 <li class="toctree-l3"><a class="reference internal" href="principles.html#find-replace-work-as-expected">Find &amp; replace work as expected</a></li>