mochajs / mocha

☕️ simple, flexible, fun javascript test framework for node.js & the browser
https://mochajs.org
MIT License
22.63k stars 3.02k forks source link

📝 Docs: Consider moving wiki information into mocha-examples and the website #5248

Open JoshuaKGoldberg opened 3 weeks ago

JoshuaKGoldberg commented 3 weeks ago

Documentation Request Checklist

Overview

Right now, there are three user-facing first-party resources containing Mocha documentation separate from this repo:

IMO it's weird to have two places to find the primary docs (the site & the wiki). Now that we're overhauling the primary docs (#5207 -> #5246), I think they're a lot better suited for including the ancillary information typically put in the wiki.

The wiki is also super old and outdated. Other than a kind edit by by @mark-wiemer it hasn't been touched since 2022, when it was receiving fewer than a half dozen edits per year on average back through 2020.

Proposal: once the docs overhaul is shipped to users, let's:

  1. Copy any relevant info from the wiki over to the docs site & examples repo
  2. Change all wiki pages to just point to the updated locations for that info
  3. Freeze the wiki and deprecate using it

Note that we don't know what community resources point to the wiki, so we can't delete it or rename pages. Those URLs need to stick around.

Additional Info

Sparked by #5247: which is one example of the quirks you can get from working with the old GitHub wiki features.

We noted in #5027 that we didn't intend to overhaul any major resources such as the wiki. But that was a year ago, and we've learned about in the maintenance cycle since. Intentions can change over time!

mark-wiemer commented 3 weeks ago

One note: we can keep the pages, but maybe remove all content and instead just have each page link to the corresponding new doc page with a "please update your bookmarks" note. Alternatively, a simple banner at the top of each page saying "This wiki is deprecated and may be out of date. Please refer to (url) instead" would work :)

Thanks for opening this, I'm still determined to close #3104 :D