JSDoc WMF theme

Documentation helps people contribute to our software and infrastructure and helps us provide basic insights in our technical community ecosystem and its needs. We are currently rebuilding our frontend documentation to better serve our users.

Previously our frontend documentation was building using a tool called JSDuck which is no longer maintained. Delaying the migration from JSDuck to JSDoc was causing issues for some projects. (See T138401#8045282, T138401#9009746, and T138401#9030517) so we went ahead and switched over our documentation and have prioritized improving the documentation (targeting the MediaWiki 1.42 release).

Feedback on these plans is welcome! Particularly if anyone has ideas about the technical feasibility of temporarily serving static snapshots of the JSDuck docs. The immediate next steps would be to open subtasks to capture the work described here.

How you can help
Let us know using the talk page:


 * How do you use the existing frontend documentation? What do you use it to build/do (e.g. gadgets, upgrading MediaWiki, other purpose)?
 * Which documentation should be prioritize porting to the new system?
 * What problems do you have with the current theme?
 * How often do you refer to the documentation?
 * What did you like and what did you not like about the old documentation?

Current roadmap
1. Research: Start researching who uses the JS HTML docs and what features are important to them, including:


 * Attempt to query pageview data for JS HTML docs from the webrequest tables in Hive
 * Put out a call for on-wiki feedback through relevant channels

2. Scope improvements to the WMF theme: Informed by user feedback and documentation best practices, compile a list of critical usability fixes in the form of Phabricator tasks with clear descriptions and acceptance criteria. In its current state, the WMF JSDoc theme has some usability issues (such as T262406 and T207383). The expectation would be that some WMF engineering time will be made available to work on these fixes within a reasonable timeframe (such as the 2024 calendar year or the 2024-25 fiscal year) either in the form of development time or Outreachy mentorship time.

3. Consider temporary mitigations: To address concerns about the impact to documentation usability while work on the theme is in progress, look into options to help mitigate that impact in the short term. For example:


 * Temporarily use another open-source JSDoc theme, such as clean-jsdoc-theme or better-docs
 * Serve static snapshots of the JSDuck docs alongside the JSDoc docs. (Although I'm not sure of the technical feasibility of this, and it does introduce extra risk, complexity, and effort.)