From f1ae6807eb1828ed3b3d2335b0b49bb507b761ea Mon Sep 17 00:00:00 2001 From: Karen Date: Tue, 26 May 2015 00:18:07 +0000 Subject: created a documentation style guide --- doc_styleguide.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 doc_styleguide.md diff --git a/doc_styleguide.md b/doc_styleguide.md new file mode 100644 index 00000000000..c1ad7a15206 --- /dev/null +++ b/doc_styleguide.md @@ -0,0 +1,29 @@ +# Documentation styleguide + +This styleguide recommends best practices to improve documentation and to keep it organized and easy to find. + +## Text (when using markdown) + +* 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, by adding '#' at the begining of it. + +* For subtitles, use '##', '###' and so on. + +* Do not duplicate information. + +* Be brief and clear. + +* To add images use +´´´ +!['NAME OF LINK']('WHERE THE LINK IS LOCATED') +´´´ + + +## 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. -- cgit v1.2.1 From cbeef2f5a86b2129cdc4f4ac4614ce9f133a5c59 Mon Sep 17 00:00:00 2001 From: Karen Date: Tue, 26 May 2015 00:18:54 +0000 Subject: fixed info box --- doc_styleguide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_styleguide.md b/doc_styleguide.md index c1ad7a15206..d4d815bd205 100644 --- a/doc_styleguide.md +++ b/doc_styleguide.md @@ -16,7 +16,7 @@ This styleguide recommends best practices to improve documentation and to keep i * To add images use ´´´ -!['NAME OF LINK']('WHERE THE LINK IS LOCATED') +'!['NAME OF LINK']('WHERE THE LINK IS LOCATED')' ´´´ @@ -26,4 +26,4 @@ This styleguide recommends best practices to improve documentation and to keep i * Images should have a specific, non-generic name that will differentiate them. -* Keep all file names in lower case. +* Keep all file names in lower case. \ No newline at end of file -- cgit v1.2.1 From 4034af81314d650c78e0bb6b40c99b6eb20c4eb2 Mon Sep 17 00:00:00 2001 From: Karen Date: Tue, 26 May 2015 00:20:18 +0000 Subject: removed unnecessary information --- doc_styleguide.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc_styleguide.md b/doc_styleguide.md index d4d815bd205..f047593f10b 100644 --- a/doc_styleguide.md +++ b/doc_styleguide.md @@ -14,11 +14,6 @@ This styleguide recommends best practices to improve documentation and to keep i * Be brief and clear. -* To add images use -´´´ -'!['NAME OF LINK']('WHERE THE LINK IS LOCATED')' -´´´ - ## When adding images to a document -- cgit v1.2.1 From 5314d6ff88ac3cd6ebf49a0a94950d8697275762 Mon Sep 17 00:00:00 2001 From: Karen Date: Tue, 26 May 2015 00:23:25 +0000 Subject: added link to documentation style guide --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b4a6102aff..c704f5ec61f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -163,6 +163,7 @@ If you add a dependency in GitLab (such as an operating system package) please c 1. [Shell commands](doc/development/shell_commands.md) created by GitLab contributors to enhance security 1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) 1. [Database Migrations](doc/development/migration_style_guide.md) +1. [Documentation styleguide](gitlab-ce/doc_styleguide.md) 1. Interface text should be written subjectively instead of objectively. It should be the gitlab core team addressing a person. It should be written in present time and never use past tense (has been/was). For example instead of "prohibited this user from being saved due to the following errors:" the text should be "sorry, we could not create your account because:". Also these [excellent writing guidelines](https://github.com/NARKOZ/guides#writing). This is also the style used by linting tools such as [RuboCop](https://github.com/bbatsov/rubocop), [PullReview](https://www.pullreview.com/) and [Hound CI](https://houndci.com). -- cgit v1.2.1 From ef32c60a5417f5379a9af4a693dc4d31196cbe52 Mon Sep 17 00:00:00 2001 From: Karen Date: Tue, 26 May 2015 00:24:40 +0000 Subject: fixed link --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c704f5ec61f..8059b95609a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -163,7 +163,7 @@ If you add a dependency in GitLab (such as an operating system package) please c 1. [Shell commands](doc/development/shell_commands.md) created by GitLab contributors to enhance security 1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) 1. [Database Migrations](doc/development/migration_style_guide.md) -1. [Documentation styleguide](gitlab-ce/doc_styleguide.md) +1. [Documentation styleguide](doc_styleguide.md) 1. Interface text should be written subjectively instead of objectively. It should be the gitlab core team addressing a person. It should be written in present time and never use past tense (has been/was). For example instead of "prohibited this user from being saved due to the following errors:" the text should be "sorry, we could not create your account because:". Also these [excellent writing guidelines](https://github.com/NARKOZ/guides#writing). This is also the style used by linting tools such as [RuboCop](https://github.com/bbatsov/rubocop), [PullReview](https://www.pullreview.com/) and [Hound CI](https://houndci.com). -- cgit v1.2.1 From 4e264076797316e0ae241f6e0c9bc18ad176587f Mon Sep 17 00:00:00 2001 From: Karen Date: Tue, 26 May 2015 00:26:57 +0000 Subject: fixed info --- doc_styleguide.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc_styleguide.md b/doc_styleguide.md index f047593f10b..670af765f3a 100644 --- a/doc_styleguide.md +++ b/doc_styleguide.md @@ -2,13 +2,11 @@ This styleguide recommends best practices to improve documentation and to keep it organized and easy to find. -## Text (when using markdown) +## 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, by adding '#' at the begining of it. - -* For subtitles, use '##', '###' and so on. +* 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. -- cgit v1.2.1