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.

Risks

• We are no longer able to use git blame to see the history of the files. We are mitigating this by adding a tag: https://github.com/mongodb/specifications/releases/tag/v1
• Links to existing RST files from JIRA and internal websites will break. We are mitigating this in four steps:
  • When converting, leave the RST file and add a note pointing to future development in the MD file, see https://github.com/mongodb/specifications/pull/1524.
  • Finish the conversion of the RST files to MD
  • Open tickets to migrate existing links in drivers and internal docs sites from RST to MD
  • Trim the contents of the RST files to only include the pointer to the MD file. This would break links to anchors on RST files, but would at least not give a 404 on the main document.

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]