Update docs conventions based on recent experience
@@ -45,7 +45,7 @@ code blocks).
Indentation
-----------
-We use 4 spaces for indentation.
+We use 3 spaces for indentation.
::
@@ -57,7 +57,7 @@ We use 4 spaces for indentation.
Code block.
-Bullet lists are the only exception to the 4 spaces rule, using 2 spaces
+Bullet lists are the only exception to the 3 spaces rule, using 2 spaces
when wrapping lines.
::
@@ -66,6 +66,21 @@ when wrapping lines.
- This is a lot of text in a single bullet which would require wrapping
across multiple lines to fit in the line length limits.
+Note that nested lists would use 3 spaces for indentation, and require
+blank lines on either side (that's the ReST syntax).
+
+::
+
+ - This is a bullet list.
+ - There is a nested list associated with this list item.
+
+ - This is a nested bullet list.
+ - With multiple bullets even.
+ - And some of the bullets have really long sentences that would
+ require wrapping across multiple lines.
+
+ - This is a lot of text in a single bullet which would require wrapping
+ across multiple lines to fit in the line length limits.
Headings
========
@@ -122,6 +137,11 @@ it.
Writing
=======
+.. note::
+
+ We're still discussing *how* pip should be capitalized in prose. The
+ current statement here is tentative.
+
pip is a proper noun, and spelt all lowercase. Do not capitalize pip as
"Pip" at the start of a sentence.
