summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJob van der Voort <job@gitlab.com>2015-06-29 15:17:53 +0000
committerJob van der Voort <job@gitlab.com>2015-06-29 15:17:53 +0000
commitfdabe90ac5f61b85e410b8f7cf059ac08d03b2f8 (patch)
tree96a574931c75b0a765fd704eeb04cc0551c4464e
parente3dbaa7027d4561bdec6860af84a9d8704d6b2a0 (diff)
downloadgitlab-ce-fdabe90ac5f61b85e410b8f7cf059ac08d03b2f8.tar.gz
update documentation styleguide
-rw-r--r--doc_styleguide.md35
1 files changed, 18 insertions, 17 deletions
diff --git a/doc_styleguide.md b/doc_styleguide.md
index db30a737f14..656bb1d17ff 100644
--- a/doc_styleguide.md
+++ b/doc_styleguide.md
@@ -4,20 +4,21 @@ This styleguide recommends best practices to improve documentation and to keep i
## Text
-* Make sure that the documentation is added in the correct directory and that there's a link to it somewhere useful.
-
-* Add only one H1 or title in each document, by adding '#' at the begining of it (when using markdown). For subtitles, use '##', '###' and so on.
-
-* Do not duplicate information.
-
-* Be brief and clear.
-
-* Whenever it applies, add documents in alphabetical order.
-
-## When adding images to a document
-
-* Create a directory to store the images with the specific name of the document where the images belong. It could be in the same directory where the .md document that you're working on is located.
-
-* Images should have a specific, non-generic name that will differentiate them.
-
-* Keep all file names in lower case. \ No newline at end of file
+- Split up long lines, this makes it much easier to review and edit. Only
+double line breaks are shown as a full line break in markdown. 80 characters
+is a good line length.
+- For subtitles, make sure to start with the largest and go down, meaning:
+`#` for the title, `##` for subtitles and `###` for subtitles of the subtitles, etc.
+- Make sure that the documentation is added in the correct directory and that there's a link to it somewhere useful.
+- Add only one H1 or title in each document, by adding '#' at the begining of it (when using markdown).
+For subtitles, use '##', '###' and so on.
+- Do not duplicate information.
+- Be brief and clear.
+- Whenever it applies, add documents in alphabetical order.
+
+## Images
+
+- Create a directory to store the images with the specific name of the document where the images belong.
+It could be in the same directory where the .md document that you're working on is located.
+- Images should have a specific, non-generic name that will differentiate them.
+- Keep all file names in lower case. \ No newline at end of file