Facilitating Docs-as-Code implementation for users unfamiliar with Markdown

Summary

Grab introduced a rich-text, WYSIWYG editor in its TechDocs portal to help non-engineering contributors work within a Docs-as-Code process despite limited familiarity with Markdown and GitLab. The editor keeps GitLab as the central storage system, uses Lexical to import and export Markdown, and supports page reordering, renaming, deletion, formatting, diagrams, and switching between normal and Markdown views. Three user journeys cover editing existing TechDocs and creating stand-alone or entity-linked documentation, with GitLab OAuth2, merge-request creation, repository access checks, and scheduler-based entity-catalog registration after merges. A phased rollout added drafts, image uploads, diagram integrations, concurrent-session visibility, and live preview, while pending-MR displays and conflict-resolution tools address collaboration risks.

Takeaways

1. 1

   Lexical was selected over Markdown-based tools such as Toast UI because its extensibility supports features including autocomplete and non-standard Markdown elements such as Kroki diagrams.

2. 2

   The editor creates or updates GitLab merge requests, checks repository access, and uses scheduler jobs to register or refresh entity catalogs after merges.

3. 3

   Live preview renders the document beside the editor so contributors can verify images, tables, diagrams, and formatting, although larger documents and external resources can create performance delays.