Determine direction for rendering help documentation in drawers
Problem to solve
In !82516 (closed) we are working towards providing help content from the Docs directly in the Product UI through the use of the drawer component. During this process, we have been working with the Technical Writing team to ensure we are doing this in alignment with the goal of standardizing this process for the future in how we display help information within the product (some guidelines were completed in gitlab-org/gitlab-services/design.gitlab.com!2857 (merged), visible here in Pajamas docs).
We have run into a few problems while working to implement this, which warrants a discussion by the larger group so that we don't run into maintenance issues or problems when documentation is updated down the road. The following are some issues we have come across:
Because the documentation is written in markdown, working to render the information more aligned to our product UI (discussed here) creates problems for management.
- Whenever an MR is implemented to pull in documentation within a drawer, that person will need to make one-off changes to accomplish this.
- Examples: Changing type styling, updating tables to use GitLab UI styling
We use different rendering engines for the Product and the Docs site, which act in different ways.
- Because these do not share the same rendering engine, information written for the Docs site may not work with the Product rendering engine
- Examples: Tags (such as "PREMIUM"), Alerts (using format like
WARNING::
in docs), Vertical Pipes (|
) character
Rendered markdown includes anchor links for heading sections (which don't work or add value when in the drawer).
Additional Context
- Discussion of some of the general issues in the Syntax Drawer MR
- Vertical pipe issue discussion
- Discussion on goal of displaying this information both in the Product and in Docs, but stored/managed in one place
- Development maintainer review concerns
- Pajamas documentation regarding UI vs Markdown Type styling
Proposal
It seems as though trying to make the information appear not as rendered markdown in the Product adds complexity and maintenance concerns. We may be better off not working against the grain here and instead keeping it as markdown in appearance. Since we are essentially providing a glimpse/excerpt into our documentation, I don't think this is necessarily problematic from an appearance/UX perspective as it is aligning close to what you see on the Docs site. There are still the concerns around things like anchor links and how we want to handle that though.
As it relates to the problems regarding the two different rendering engines, I am unsure what the best solution is for that. Will we always require the need to have separate rendering engines, or could we utilize one shared one? Do we simply need to solve for some of the differences knowing it will remain an ongoing limitation?
My goal for this issue is to determine the best solution and direction for these problems together, so we have a shared understanding of the impacts of these decisions and how we want to move forward. With !82516 (closed) being the first instance where we have worked to pull in docs into a drawer, we want to make sure to get these details ironed out for future uses so we have consistency and a framework for how this can be achieved successfully.