Add doc guidelines on documents naming and location
What does this MR do?
Add guidelines on the structure of the documentation.
What are the relevant issue numbers?
Merge request reports
Activity
mentioned in issue #3349 (moved)
Added 1 commit:
- ff440799 - Add doc guidelines on documents naming and location
24 | `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under `doc/user/admin_area/`. | 25 | `doc/api/` | API related documentation. | 26 | `doc/development/` | Documentation related to the development of GitLab. Any styleguides should go here. | 27 | `doc/legal/` | Legal documents about contributing to GitLab. | 28 | `doc/install/`| Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). | 29 | `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | 30 31 --- 32 33 **General rules:** 34 35 1. The correct naming and location of a new document, is a combination 36 of the relative URL of the document in question and the GitLab Map design 37 that is used for UX purposes ([source][graffle], [image][gitlab-map]). 38 1. When creating a new document and it has more than one word in its name, 39 make sure to use underscores instead of spaces or dashes (`-`). For example, -
@axil I think we should do the opposite, as recommended by Google Engs: https://www.youtube.com/watch?v=5UPc6-Te_AU
Edited by username-removed-236961 
@virtuacreative that would be cumbersome as we use underscores all over the place from back when GitLab was first created
😛 Thanks for the video link though, very informative :)
Edited by Achilleas Pipinellis-
@axil I'm not suggesting that we should change all the URLs! I'm kinda crazy, but not enough to suggest it
😜 What I'm suggesting is not having underscores as the default for now on, for new pages. Make the standards with dashes, so we will be aligned with super-google and SEO.
-
Hmm, I'm not sure we should change it, I mean does it really affect SEO that much? The guy in the video suggested to stick with underscores if you are already using them.
@mitchellwright do you have an opinion on this?
Probably not worth messing with. Here is a more recent article, with a direct quote from John Mueller:
https://www.seroundtable.com/google-doesnt-care-about-underscores-vs-dashes-in-urls-22180.html
I think changing things would cause more harm than good. Moving forward we could change and only use hyphens if we wanted, but it's probably not a big deal at this point.
-
I think I'm covered :) Thanks @mitchellwright !
I don't know the difficulty of changing how it's done. I don't think it is a problem to make the change for all future docs, however depending on the difficulty, I don't think there's a ton of advantage. This isn't a change that is going to give us some incredible SEO advantage. It would be minimal, if not imperceptible so I wouldn't advise we do it if there is a large effort involved.
-
Perhaps I'm missing something here... I don't see this as a big deal at all... I think this is just a matter of using hyphens instead of underscores in new urls, for complying with SEO standards, that's all. Please ignore me if this change would cause any problems/issues/difficulties, it's more an observation/suggestion than anything else.
mentioned in commit 91030230
