Remove the documentation in Help section from the Rails app
The Help section has caused a lot of headaches, and I have been a big proponent of removing it from the Rails app due to the constraints it introduces.
/help
Problems with - Holds back docs.gitlab.com from being made great again.
- Designers must consider it when implementing/updating the interface.
- Tons of problems with routes in Rails (
/help/help
, broken routing to the Getting Started with Pipelines page, etc.). - Constrains the structural design and updating of the documentation.
- Slows the technical writing team down.
-
Part of the reason docs.gitlab.com has such a terrible build system.(we switched to a proper static site generator since and deploying to Pages) - Slower than it should be because it’s part of the main Rails app.
- Any "advanced features", e.g. a table of contents, need to be implemented in our static site as well as Rails. This is a massive pain for making the Help/Documentation easier to use.
You know the reason nobody has an m.
site anymore? It doubled the work they had to do to implement a feature, they were essentially reimplementing it entirely for mobile. This is what we're doing here, and it sucks.
Considerations for removing it
I'm not suggesting we just rip out the Help section, the idea would be that it be replaced with some very basic information, links to docs.gitlab.com, and that's it.
In order to ensure that the docs will be in-sync with the on-premise version users are working with, the documentation site either needs to have a versioning system (based on the state of the GitLab repository's tags presumably), or we have to ship a static site alongside every GitLab instance to serve as their documentation. It cannot continue to be embedded in the Rails app, as this is what's causing the problems I discussed above.
We need to:
- Have some way to make sure users are viewing the correct version of the documentation for their instance.
- Ensure that, if we use docs.gitlab.com, enterprise customers are okay with that.
- Replace Help links from the Search suggestions and help text with their new counterparts.
- Make sure replacing this doesn't prevent the Docs team from adding new documentation on new features, it has to essentially be fully replaced in a single release.