We need to get started with the technologies we've chosen for the documentation changes, and begin getting some dogfood feedback.
We'll implement with a subset of documentation content that will
- rewrite the selected content into the selected markdown flavor and store it in the SonarQube GitHub repo
- generate the marked-down content to file
- properly handle links between documentation segments (E.G. For more, see Quality Profiles)
- make the generated content available in the UI
- make the generated content available in a website format
- make the generated content available in a PDF (nice to have)
We must include the necessary metadata in any documentation-specific URLs (<noindex>) to ensure pages in public instances of SonarQube aren't indexed by Google, et al.
TBD: Given a page like Quality Profiles, can we successfully:
- break it down into components
- link each component to only the relevant interface pages and present them there
- reassemble the pieces in some order for the static site
GatsbyJS for static site generation. Markdown conversion & static site generation will happen as a normal part of compile (so that every build is deliverable #continuousdelivery).
We'll target the following User Guide and Project Administration Guide pages in this sprint:
- Fixing the Water Leak
- Quality Gates
- Quality Profiles
Project Administration Guide
- Narrowing the Focus
- Branch Plugin
The documentation will now be accessible easily through the "?" help icon in the top bar. Clicking on this icon will now deploy a dropdown. Inside, users will find suggestions to specific pages of the documentation as first items. Those suggestions will change for each page of the application, and are to be defined with documentation team. Then they will find the link to Documentation index. Finally, helpful links to get support and news are available at the bottom of the dropdown. All links in this dropdown open new tabs to external sites. However only documentation items provide an icon to explain this (it's pretty obvious for the news and support links because of logos).
Those helpers and clickable and display definitions and additional links to documentation if needed.
Note: we will get rid of the blue "?" helpers already existing in the application. They will be replaced by those grey ones and have the same behavior (clickable instead of hoverable).
Because of this clickable behavior, a helper cannot be displayed inside another clickable element. For example, here the "built-in" badge will provide a helper on theright part of the screen, but not when displayed in the left sidebar.
As a general rule, the helpers are located on the right of the elements that need explanation. For right-aligned elements, the helpers will float aside to not spoil the design and keep alignments visually appealing.
Because of the new behaviour and style of these "?" indicators (grey and clickable instead of hoverable), we have to change the pattern previously used to advertise the enablement of features such as branches. Such pattern will now be a "+" icon.
Some explanations don't necessary need to be hidden behind a "?" helper. For general concepts that apply to a whole page, our current layout containing a headline + one paragraph is already efficient. When there is enough space, this reduces the interaction cost as users don't have to search for the helper and then click on it.
This iteration will not include any content which must be suppressed for SonarCloud users so that division of audience will not be dealt with in this sprint.