documentation/Writing-the-content.md

@@ -49,6 +49,29 @@ Please **don't create a new line in the middle of a sentence**, as that creates
   * **Always prefer https links when available**, to protect the privacy of our readers.
   * Make sure that the link is the shortest version possible, without suffixes like: `?ftag=COS-05-10aaa0b` or other random stuff. Take everything possible out of the link and leave it to its minimal (as long as functional) expression.
 
+### Lists
+
+Lists are either ordered (numbered), or unordered (bullet points).
+
+You can write ordered lists like this. The order the numbers are in doesn't matter, they'll be renumbered when converted to HTML.
+
+```
+1. the first thing
+2. the second thing
+3. and a third thing
+```
+
+You can write unordered lists like this. You can use an asterisk (`*`), a dash (`-`), or a plus (`+`).
+
+```
+* foo
+* bar
+* baz
+```
+
+**Warning**: Note the space between the number/bullet and the list text. Forgetting the space is a common cause of confusion, because it can be hard to notice what you've done wrong.\
+**Warning**: Don't add blank lines between list items, or they'll render as separate lists. This is a quirk of Lektor's markdown parser (mistune).
+
 ### How to write commands
 
 - When writing linux commands, remember that: