Details
-
Epic
-
Resolution: Unresolved
-
Unknown
-
None
-
None
-
None
-
Not Needed
-
0
-
0
-
0
-
100
-
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: