Skip to content

Improve GitLab UI's documentation

We currently document GitLab UI's development guidelines in the CONTRIBUTING.md file. We also have some guidelines documented in the README.md.

Having most of the guidelines documented in CONTRIBUTING.md makes the document kinda hard to digest and to maintain. More so, the fact that CSS guidelines live in the README makes our documentation even more confusing.

Let's work on improving these development guidelines by making each main section easier to discover and to read.

Improvement plan

  • Break down CONTRIBUTING into multiple files and use CONTRIBUTING as a table of contents for these new files: !1008 (merged)
  • Use the same approach for CSS guidelines: !1008 (merged)
  • Create documentation guidelines: We currently don't have clear guidelines on how to write documentation in GitLab UI, which results in a lack of consistency in our components' documentation, as well as in development guidelines. Here are a few things that we could document in our documentation guidelines:
    • Components naming convention: let's make it clear how to refer to components in our docs. Should we use pascal case (GlComponentName)? Kebab case (gl-component-name)?
    • Enforce similar guidelines to refer to GitLab UI as a project: should we refer to GitLab UI, or to gitlab-ui? Or something else?
    • Idem for GitLab UI as a package: should we refer to @gitlab/ui? gitlab-ui? ...
    • Let's define what we expect to see in each component's documentation: usage examples, browser compatibility, edge cases, etc.
    • If possible, create a template for the item above
    • Add v-model table to component reference, in addition to props and slots tables: !1262 (merged)
    • [-] Add scoped slot props info to slots table
    • Add a Link to source button for each component, pointing to the correct version of the source file in GitLab. !2249 (merged)
    • Add a docs linter !2250 (merged)
  • Improve individual sections. The following subitems depend on !1008 (merged) being merged:
    • doc/contributing/adding_components.md: This section is currently presented as a list which is a very constrained format, it makes it hard to really dive into details for each step in the process. Let's refactor the whole document by using headings for each main step necessary to add a new component to GitLab UI and let's add a much details as necessary below those headings. !1133 (merged)
    • doc/contributing/adding_css.md: Let's make sure that the guidelines documented here actually align with the working group's decisions (see #485 (comment 269992971)) !1245 (merged)
    • doc/contributing/automatic_documentation.md: Make sure that this section's content is up-to-date.
    • doc/contributing/commits.md: This section is fairly new and should be up-to-date, however we might want to review our commit types' descriptions to prevent confusion (see !1015 (comment 272791949)): !1246 (merged)
    • doc/contributing/local_gitlab_testing.md: Let's make sure that the guidelines documented here work as expected. Update and reformat as needed.
    • [-] doc/contributing/troubleshooting.md: This section contains a single item which is formatted like one of our FAQ's items. Should we move that item into the FAQ? Or on the contrary, move the FAQ into this guide?
  • Document Danger? We should at least make it clear that it's up to MR authors to use their best judgement when being presented reviewers suggestions by Danger's roulette (see #598 (comment 278665369)) !2253 (merged)
Edited by Paul Gascou-Vaillancourt