Uploaded image for project: 'Drivers'
  1. Drivers
  2. DRIVERS-2789

Use Markdown for Specifications Documentation

    XMLWordPrintableJSON

Details

    • Icon: Epic Epic
    • Resolution: Unresolved
    • Icon: Unknown Unknown
    • None
    • None
    • None
    • Not Needed
    • 0
    • 0
    • 0
    • 100
    • Hide

      2024-02-02

      • 2 specs have been merged
      • 2 specs are in review
      Show
      2024-02-02 2 specs have been merged 2 specs are in review

    Description

      Summary

      Update our drivers specification source documents to use Github Flavored Markdown.

      Motivation

      Following up on DRIVERS-983, there is a renewed concern that is it prohibitively difficult to use RST. Additionally, there is a new internal initiative to use Pine for R&D docs, which consumes Github Flavored Markdown.

      Proposal

      We can use pandoc and a custom script to most of the heavy lifting to convert the existing RST documents to Markdown. Each spec author would be tasked with running the script and ensuring that the resulting document(s) are correct.

      We have verified that GitHub Flavored Markdown accommodates all of the features we were using in RST, except for the fact that Admonitions (e.g. inline warning box) are not uniformly specified. Docusaurus (which is used by Pine) has one syntax, while GitHub recently standardized another. We should prioritize rendering on Docusaurus in this case, since the drivers and other internal teams will most commonly use the rendered documentation.

      As a pilot, I will make a PR to add the script and convert the CSOT specification. Once that is done, we can open the other child tickets on this Epic for each spec.

      Once we have about a half dozen specs, we can turn on the Pine integration (which will be its own child ticket), as a carrot for everyone to update their specs.

      Implementation Plan

      I will run the migration script and open the PRs, in order to avoid merge conflicts. I will ping the spec owners for review.
      The spec owners will:

      • Verify the new content is correct (and update as necessary).
      • Verify that the links are correct (links in Markdown files will be verified in CI)
        Once the PR is merged, I will open a PR for the next ticket.

      Cast of Characters

      Engineering Lead:
      Document Author: Steven Silvester
      POCers:
      Product Owner:
      Program Manager:
      Stakeholders:

      Channels & Docs

      Slack Channel

      [Scope Document|some.url]

      [Technical Design Document|some.url]

      Attachments

        Activity

          People

            steve.silvester@mongodb.com Steve Silvester
            steve.silvester@mongodb.com Steve Silvester
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

              Created:
              Updated:
              4 weeks, 3 days