diff options
author | Achilleas Pipinellis <axilleas@axilleas.me> | 2016-06-13 16:26:43 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axilleas@axilleas.me> | 2016-06-13 16:26:43 +0300 |
commit | aa48eeef17e9bceff4e198815f8f1b566fdaf84f (patch) | |
tree | d1bca69fcb2431dfa628695e3e75cbcdcf7373a8 | |
parent | e5b974bda77c0451dcbce24770e7f0e7c08c5f19 (diff) | |
parent | d1abbb3b662bd41a3b58eeb60c5c0740adff986c (diff) |
Merge branch 'doc-styleguide-move-locations' into 'master'
Add guide on changing a document's location
## What does this MR do?
Add a documentation styleguide when changing a document's location.
## What are the relevant issue numbers?
https://gitlab.com/gitlab-org/gitlab-ce/issues/3349
See merge request !4624
-rw-r--r-- | doc/development/doc_styleguide.md | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index dbaa7eff410..f5d97179f8a 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -141,6 +141,48 @@ Inside the document: [ruby-dl]: https://www.ruby-lang.org/en/downloads/ "Ruby download website" +## Changing document location + +Changing a document's location is not to be taken lightly. Remember that the +documentation is available to all installations under `help/` and not only to +GitLab.com or http://docs.gitlab.com. Make sure this is discussed with the +Documentation team beforehand. + +If you indeed need to change a document's location, do NOT remove the old +document, but rather put a text in it that points to the new location, like: + +``` +This document was moved to [path/to/new_doc.md](path/to/new_doc.md). +``` + +where `path/to/new_doc.md` is the relative path to the root directory `doc/`. + +--- + +For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to +`doc/administration/lfs.md`, then the steps would be: + +1. Copy `doc/workflow/lfs/lfs_administration.md` to `doc/administration/lfs.md` +1. Replace the contents of `doc/workflow/lfs/lfs_administration.md` with: + + ``` + This document was moved to [administration/lfs.md](../../administration/lfs.md). + ``` + +1. Find and replace any occurrences of the old location with the new one. + A quick way to find them is to use `grep`: + + ``` + grep -nR "lfs_administration.md" doc/ + ``` + + The above command will search in the `doc/` directory for + `lfs_administration.md` recursively and will print the file and the line + where this file is mentioned. Note that we used just the filename + (`lfs_administration.md`) and not the whole the relative path + (`workflow/lfs/lfs_administration.md`). + + ## API Here is a list of must-have items. Use them in the exact order that appears |