Uploaded image for project: 'Minimal Marketable Features'
  1. Minimal Marketable Features
  2. MMF-1235

First baby step for embedding docs in the Platform and generate a static site

    Details

    • Type: MMF
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Labels:

      Description

      Why

      We need to get started with the technologies we've chosen for the documentation changes, and begin getting some dogfood feedback.

      What

      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

      How

      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).

      Which docs

      We'll target the following User Guide and Project Administration Guide pages in this sprint:
      User Guide

      • Fixing the Water Leak
      • Quality Gates
      • Quality Profiles
      • Rules

      Project Administration Guide

      • Narrowing the Focus
      • Webhooks

      Plugins

      • Branch Plugin

      Current design proposition

      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).

      On top of this, grey helpers with a "?" icon will be displayed next to words and concepts that need help to be fully understood by new users.

      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.

      In that objective, we might evaluate the possibility of adding a headline and small paragraph in some places where we currently don't have them. Example:

      Out of Scope

      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.

        Attachments

        1. Inline_Metrics_Definitions_06.png
          Inline_Metrics_Definitions_06.png
          385 kB
        2. Inline_Metrics_Definitions_07.png
          Inline_Metrics_Definitions_07.png
          220 kB
        3. Embedded_Documentation_01.png
          Embedded_Documentation_01.png
          274 kB
        4. Embedded_Documentation_02.png
          Embedded_Documentation_02.png
          267 kB
        5. Embedded_Documentation_03.png
          Embedded_Documentation_03.png
          187 kB
        6. Embedded_Documentation_04.png
          Embedded_Documentation_04.png
          191 kB
        7. Embedded_Documentation_05.png
          Embedded_Documentation_05.png
          293 kB
        8. Embedded_Documentation_06.png
          Embedded_Documentation_06.png
          367 kB
        9. Embedded_Documentation_07.png
          Embedded_Documentation_07.png
          257 kB
        10. Embedded_Documentation_08.png
          Embedded_Documentation_08.png
          183 kB
        11. Embedded_Documentation_00.png
          Embedded_Documentation_00.png
          281 kB

          Issue Links

            Activity

              People

              • Assignee:
                christophe.levis Christophe Levis
                Reporter:
                ann.campbell.2 Ann Campbell
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: