Simplify and update documentation style guide
Existing style guide: https://docs.gitlab.com/ce/development/doc_styleguide.html#location-and-naming-of-documents
Goal: a new users can refer to the style guide and know exactly where to create new documentation articles. To do this we need a simple structure which requires the least amount of rules to determine where content should go.
To start the discussion, I propose a flat-as-possible structure rather than a deep hierarchy.
Activity
Let me link to the great issue 3349, where we had the discussion again https://gitlab.com/gitlab-org/gitlab-ce/issues/3349 :) There are some good comments in there.
I particularly want to stress out that:
This issue is about the underlying path of docs, not what we will present to the user in the end. What we present to the user and how we do that is entirely up to us and we could split things like we want.
To start the discussion, I propose a flat-as-possible structure rather than a deep hierarchy.
Right now, our deepest level is 3. I agree we should not nest very deeply and possibly 3 is maybe too much, it should be the limit.
The flat-as-possible hierarchy is what we had in the past and decided it didn't quite work (specifically is you see the
workflow/dir). Do you have any concrete examples?I do feel strongly about nesting at least under the top-level directories such as
user/,administrator/and similar. Before we had this guideline it was a free-for-all - actually, most docs landed under 'workflow/'. It just became a dumping ground and made it impossible to provide sane navigation. By nesting in logical directories we can probably do some automation to generate good navigation in the future.To be honest, I don't find the current guidelines to be too confusing. Maybe admin_area is a bit too granular, but I like the other recommendations.
This issue is about the underlying path of docs, not what we will present to the user in the end. What we present to the user and how we do that is entirely up to us and we could split things like we want.
IMO we should as closely match the actual structure to how we would present it to the user. Updating manual navigation is a mess and is far more confusing to the user writing the docs. Ideally, we should be able to generate navigation based on the hierarchy.
-
IMO we should as closely match the actual structure to how we would present it to the user. Updating manual navigation is a mess and is far more confusing to the user writing the docs. Ideally, we should be able to generate navigation based on the hierarchy.
I agree. This is kinda relevant btw https://gitlab.com/gitlab-com/gitlab-docs/issues/48. I think we really need to get yaml frontmatter into play for our docs.
-
@connorshea that's an option, but even if this is not the case, I don't think people would care that much if it was there.
-
I think that following our UX map makes things easier https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png.
