Skip to content
GitLab Next
Closed (moved) (moved)
Created by Achilleas Pipinellis (OOO | back on july 25th)@axil🌴Developer2 of 6 tasks completed2/6 tasks

[meta] Documentation restructure

The documentation hierarchy can be vastly improved by providing:

  1. A standard way to store images (partially implemented, but we can do better)
  2. Better layout and organization of directories (also related https://gitlab.com/gitlab-org/gitlab-ee/issues/145). The current documentation tree structure can be seen in the snippet: https://gitlab.com/gitlab-org/gitlab-ce/snippets/13320. A mock documentation tree structure with the new hierarchy: https://gitlab.com/gitlab-org/gitlab-ce/snippets/15004

Changed paths

Track down changed paths as they happen along with their MR (relative to doc/):

Changes

This section is documented in the doc styleguide http://docs.gitlab.com/ce/development/doc_styleguide.html#location-and-naming-of-documents

After a call with Drew, we decided it would be best to have as few top level directories as possible (dirs right under doc/).

With that in mind, we decided to use the following names and hierarchy:

Directory What belongs here
user User related stuff. Anything that can be done within the GitLab UI goes here including admin/
administration Stuff that require access to the server where GitLab is installed
api API stuff
development Stuff related to the development of GitLab. Any styleguides should go here.
legal Legal stuff about GitLab
install Probably the most visited directory, since installation.md is there. Ideally this should go under administration/, but it's best to leave it as-is in order to avoid confusion (still debated though)
update Same with doc/install/. Should be under doc/administration/, but this is a well known location, better leave as-is, at least for now.

General rules:

  1. The correct naming and location of a new document, is a combination of the relative URL of the document in question and the GitLab Map design that is used for UX purposes (source, image).
  2. When creating a new document and it has more than one word in its name, make sure to use underscores instead of spaces or dashes (-). For example, a proper naming would be import_projects_from_github.md. The same rule applies to images.
  3. There are four main directories, user, administration, api and development.
  4. The doc/user/ directory has five main subdirectories: project/, group/, profile/, dashboard/ and admin_area/.
    1. doc/user/project/ should contain all project related documentation.
    2. doc/user/group/ should contain all group related documentation.
    3. doc/user/profile/ should contain all profile related documentation. Every page you would navigate under /profile should have its own document, i.e. account.md, applications.md, emails.md, etc.
    4. doc/user/dashboard/ should contain all dashboard related documentation.
    5. doc/user/admin_area/ should contain all admin related documentation describing what can be achieved by accessing GitLab's admin interface (not to be confused with doc/administration where server access is required).
      1. Every category under /admin/application_settings should have its own document located at doc/user/admin_area/settings/. For example, the Visibility and Access Controls category should have a document located at doc/user/admin_area/settings/visibility_and_access_controls.md.

Next steps

Questions

  • What happens if a feature is in both projects and groups?

Advantages

  1. Clear hierarchy. Right now workflow is getting a big pile of everything.
  2. We will be able to have meaningful URLs like doc.gitlab.com/user/projects/merge_requests.html. With this you immediately know that you are navigating a user related documentation concerning projects that is about merge requests. Another example: doc.gitlab.com/administration/incoming_email/postfix.html. You immediately know that it's related to administration stuff and is about the incoming email feature and especially postfix.
  3. Ability to check of missing docs. Since the path of docs will following a pattern, we will be able to know what is missing. Not the most accurate way to test this, but useful for a big percentage.

Disadvantages

Links pointing straight to the repo will break. Nothing will break, we will keep the existing docs for as long as we can, and we will just change their contents just pointing to the new locations (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4624)

In docs.gitlab.com we will use redirects https://gitlab.com/gitlab-com/doc-gitlab-com/issues/64 We will eventually migrate the doc website to GitLab Pages, so this should be avoided.

I think it's worth it if we want to establish a default documentation hierarchy. We can make use of the social media to notify people about this and plan ahead.

My main concern is the install/ dir which according to the plan should be moved under administration/. The installation guide is probably the most viewed document. This will probably won't change.

I strongly believe that we should make the move, the earlier the better. We can keep the docs under install/ and modify them to point to the new location. Then in next major GitLab version or in 6+ months we can ditch the install/ dir altogether.