Epic Name:Onboard documentation
The number of questions on StackOverflow and in the Google group that can be answered with a simple link to the documentation is evidence that simply having a documentation link in the SonarQube footer is not sufficient. First, not all users have Internet access from work. Second, even if they do the question of matching the version of the documentation to the version of the platform remains an issue; that footer link always goes to the documentation "head" or current version. If I follow it from 6.0, for example, I may end up more confused than I started as I read docs for features that aren't present in my version or that have changed since my version.
Additionally, our current documentation process and versioning scheme are cumbersome and difficult to maintain, and will become even more problematic as we move toward continuous delivery. The current workflow is that the ad-hoc Documentation team is gathered several weeks before release is anticipated to review what changes might require documentation updates, and to hand out assignments. Over the course of the following weeks the changes are gradually made and those changes may or may not be reviewed by someone else before publishing. Not only does this make it easy to miss changes, but that kind of timeline is simply incompatible with continuous delivery. If the platform is releasable at any given moment, the docs must be ever-ready as well. Further, the process of actually publishing a new version of the documentation via Confluence space copy, while not difficult (only tedious), relies on a workflow that is less and less supported by the tools in use (Confluence and Scroll Versions). And as those tools seem to evolve away from our current use case, managing the documentation site as a whole becomes more difficult with each subsequent tool upgrade. Further, some bug in Confluence and/or ScrollVersions has blocked our ability to send page update notifications, so we've lost oversight of what's being changed, and that bug or some other bug occasionally blocks even our ability to smoothly save page changes.
Beyond that, users, particularly new users, are often adrift in the interface (despite our excellent UX ;-D), as they're presented with core concepts such as the Leak that are entirely unfamiliar to them. Although these things are well explained in the documentation, that documentation is too "far away" to be helpful. This problem is exacerbated when you consider SonarCloud, which has no documentation of its own. Currently we can only refer its users to SonarQube documentation, which may add additional confusion.
Documentation currently housed in the SONAR space in the docs wiki will no longer "live" Confluence, but in the SonarQube platform / GitHub. Documentation in the SCAN and PLUG spaces will remain in Confluence for now.
At the same time, we retain a need to make documentation available to people who don't yet have a running instance of SonarQube. For each SonarQube version, we will generate a static docs site. When crafting the static site, we must make every reasonable effort to either maintain link continuity.
We will have the ability to specify whether content is targeted to SonarQube (embedded) users, SonarQube static docs users, or SonarCloud users because for instance content like JMX Beans isn't relevant for SonarCloud
- We must include the necessary metadata (<noindex>) to ensure pages in public instances of SonarQube aren't indexed by Google, et al.
The static documentation site will be generated as a normal part of the build, and made live as part of the release process.
This move of the documentation into the SonarQube repository will shift the the creation of documentation "new lines" from just prior to release backwards into the development/PR process or perhaps even earlier into MMF specification.
Once we move the SONAR space content out of Confluence, several of its features will be missed:
- The ease of hitting "Edit" and then using a WYSIWYG editor
- We'll never be able to make writing markdown in a GitHub repo that easy, but training should help
- Notifications; Confluence allows you to watch pages and spaces
- GitHub File Watcher allows you to set up watches on subsets of public GitHub repositories by path regex, and emails you when changes are made. Short-term, we can use this to "watch" docs files in the public SonarQube repository. The email notification contains a link to the changeset, which gives a red/green highlight similar to what's in Confluence's notifications.
- Visibility of change history
- It takes a little more digging to get to this on GitHub, and you cannot easily compare two random points in a file's history, but it is available, E.G.
- Ability to make immediate changes to published docs
- For severe mistakes or omissions, we could handle this with a re-generation-from-branch and re-publish of the docs - i.e. a Bug Fix release, although the procedure would have to be worked out, and would certainly not be the quick fix we have the ability to make now.
- For less severe mistakes or omissions, we can simply view corrections as we do any other small bug - something to be fixed in the next release.
We'll build this. (
MMF-1235) Markdown conversion & static site generation will happen as a normal part of compile (so that every build is deliverable #continuousdelivery).
Documentation for all editions will be available to all users. This is easiest from a technical standpoint, and has the happy side effect of promoting our paid features.