Skip to content

[Markdown] Shipping JS docs in Markdown #5808

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wbamberg opened this issue Jun 9, 2021 · 0 comments
Closed

[Markdown] Shipping JS docs in Markdown #5808

wbamberg opened this issue Jun 9, 2021 · 0 comments
Labels
MDN:Project Anything related to larger core projects on MDN needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened.

Comments

@wbamberg
Copy link
Collaborator

wbamberg commented Jun 9, 2021

This bug is to list and track how we will ship the conversion of the JS documentation into Markdown.

As a starting point:

  • we have a resolution for all conversion formatting questions (except one, which I think is going to be relatively simple)
  • we have a converter that can generate beautiful Markdown from the JS docs
  • we have a branch of Yari that can render the converted Markdown back into MDN pages
  • we have a PR that converts the JS docs into Markdown and includes preview URLs for the rendered pages: HTML ➡️ Markdown: Web/JavaScript #5193

I'd like to propose these steps for getting from here to having the JS docs in Markdown:

  1. A fairly small group of people try out the converted Markdown and the rendered pages and report issues until we think it's good enough to ship.
  2. We finish on updating the Yari tooling for Markdown (tracked in https://github.com/mdn/yari/labels/markdown )
  3. We make sure localization leads are aware of this project, understand what is needed, and are comfortable with the likely timelines.
  4. Once (2) is done, land the Yari part of this. After that anyone can experiment with Markdown just using mdn/content.
  5. Once 1-4 are done, choose a fairly small (tens of pages) and relatively inconspicuous bit of the JS docs, convert it, and commit the changes to the site.
  6. Once 5 is done, have a few people go through trying out edits to the docs and preparing PRs.
  7. Once that all feels good, minimise the number of in-flight JS PRs we have, and convert all the other JS docs.
  8. Update the contribution docs.
@wbamberg wbamberg added needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened. MDN:Project Anything related to larger core projects on MDN labels Jun 9, 2021
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 10, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
MDN:Project Anything related to larger core projects on MDN needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened.
Projects
None yet
Development

No branches or pull requests

1 participant