Docs: guidelines for using SVG icons
Problem to solve
We have added the support for using GitLab SVGs directly in the documentation through a custom markdown markup.
On the style guide, we say we can use them, but we do not say when to use and when not to.
For nav steps, if some of them have the icon and some of them don't, we're increasing technical debt by introducing inconsistencies. Besides, using the icons in all nav steps is quite harder to maintain.
If we require all nav steps to include the icon, besides breaking /help
, I honestly think we're over-complicating how to document GitLab and we'll be making contributions to the docs harder.
Note that all links to docs from the UI take the user to /help
.
The /help
issues will be resolved by &693 (closed), but that doesn't change:
- Contributions will still be harder
- Nav steps will be still harder to maintain
- The lack of a guideline will still be introducing technical debt to the documentation.
Proposal
- Avoid over-using icons.
- Include them in nav steps only when the button to click doesn't have text. For example, GL's admin area button represented by the wrench:
- Do not use it in nav steps if it's not necessary, for example:
click **{Git-merge}** **Merge Requests**, and click **New Merge Request**.
It doesn't only look bad on/help
but is also very confusing to read.
Who can address the issue
TW Style Committee