[DRIVERS-2789] Use Markdown for Specifications Documentation Created: 05/Dec/23  Updated: 07/Feb/24

Status: Designing
Project: Drivers
Component/s: None
Fix Version/s: None

Type: Epic Priority: Unknown
Reporter: Steve Silvester Assignee: Steve Silvester
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
Driver Changes: Not Needed
Quarter: FY25Q1
Start date:
End date:
Calendar Time: 4 weeks, 3 days
Scope Cost Estimate: 0
Cost to Date: 0
Final Cost Estimate: 0
Cost Threshold %: 100
Detailed Project Statuses:

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]



 Comments   
Comment by Githook User [ 07/Feb/24 ]

Author:

{'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}

Message: DRIVERS-2789 Convert Auth Spec to Markdown (#1501)

Comment by Githook User [ 06/Feb/24 ]

Author:

{'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}

Message: DRIVERS-2789 Convert Benchmarks Spec to Markdown (#1498)

  • address review
Comment by Githook User [ 31/Jan/24 ]

Author:

{'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}

Message: DRIVERS-2789 Convert CMAP Spec to Markdown (#1500)

  • Cleanup
  • convert to MD tables
  • fix migration script and update links
  • update script to handle absolute paths
  • update script to handle all path types
Comment by Githook User [ 23/Jan/24 ]

Author:

{'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}

Message: DRIVERS-2789 Convert BSON Corpus Spec to Markdown (#1499)
Branch: master
https://github.com/mongodb/specifications/commit/cea087babea68571fa4068ace6b2d326c3a0a22d

Comment by Githook User [ 04/Jan/24 ]

Author:

{'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}

Message: DRIVERS-2789 Use Markdown for Specifications Documentation (#1482)

  • DRIVERS-2789 Use Markdown for Specifications Documentation
  • add changelog entry
  • Update references
  • Revert "Update references"

This reverts commit f30793e0e4e70595f3ba8945256060fee89aca04.

  • Handle links to the markdown file
  • formatting
  • Update source/enumerate-collections.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Update source/read-write-concern/read-write-concern.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Update source/transactions/transactions.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Update source/uri-options/uri-options.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Update source/index-management/index-management.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Update source/crud/crud.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Update README.md

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • address review
  • fix link
  • Update source/change-streams/change-streams.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Update source/uri-options/uri-options.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Update source/uri-options/uri-options.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Update source/uri-options/uri-options.rst

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

  • Wrap at 120 chars
  • clean up csot changelog

---------

Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Branch: master
https://github.com/mongodb/specifications/commit/eef59d9d386bb054e0eb59e6bd540a030186f899

Comment by Steve Silvester [ 21/Dec/23 ]

I changed it to Designing. Once the initial PR is merged I'll make the tickets for spec owners and move it to Teams Implementing.

Generated at Thu Feb 08 08:26:25 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.