The current offering for embedded documentation is small enough to easily find everything that's there simply through browsing. Soon that will not be the case. Further, as the documentation site grows, it will become organized more and more hierarchically, meaning that if you already know where to find what you're looking for, you're in good shape. If you don't... well, it will be difficult.
Users will want to be able to search the documentation to find what they're looking for by keyword, and we should make that easy and powerful.
At the same time, once a user has found what she's looking for in the docs, she'll want an easy way to get from the documentation to the parts of the interface it describes. However, such links must be offered appropriately. For instance, Anonymous should not be offered a link to Administration > Projects > Management, but should be shown that path through the interface instead, as should anyone reading the static docs site.
We will index the embedded documentation and add search functionality within the embedded docs site.
See the search in action (prototype):
We will also enable - where possible - smart linking from the docs back into the SonarQube interface. Specifically, it isn't practical to link from the documentation into project administration (which project?), but it should be possible to link to the Projects page, the Rules page, and so on. Further, we should be able to selectively link to administrative pages if the user has permissions, and display the path through the interface (E.G. Administration > Security > Users) for users without permissions.
Since those links will need to be substituted for paths through the interface in the static, generated site, they will be made with metadata. Specifically, we'll use an identifier tag in the markdown, and docs generation will substitute either the path or the link as appropriate. The actual link text should be provided in the markdown, rather than imposed (maybe defaulted?) in the metadata.
Documentation will have opened from the "?" menu into a new window. Interface links in the docs will open yet another window.
Additionally, we'll expand the range of supported markdown to include (
- use warning/info alerts in the documentation (with markdown syntax) inside documentation (E.G.).
- have collapsible sections (relevant for E.G. language-specific metric definitions)
- icons: , , , (E.G.)
- linebreak in a table cell
- allow italics in heads. Currently you can italicize, but the font weight doesn't match
- ability to inline (without top/bottom linebreaks) sonarqube-/sonarcloud-only content
- page-level ToC (E.G.)
- the ability to scope a page to only the static web site
- control the order of pages and directories (e.g. "Branches") in the docs index
Regarding the search, for the static site, there are different possibilities that could be integrated smoothly (e.g. https://www.gatsbyjs.org/docs/adding-search/). On the embed documentation side, that still need to be discussed.
We already have a JSON file to link suggestions to SQ pages. We could use the same file to also store the URL of each page and a text defining how to reach them. The URL would be use on the embed documentation, and the text would be use on the static site. We should add a custom markdown tag to handle those kind of links/texts.
We should add custom markdown tags to handle "warning" and "info" markers. Also, links inside the documentation should have the `target="_blank"` attribute.