Talk:Requests for comment/Documentation overhaul

Previous page history was archived for backup purposes at Talk:Requests for comment/Documentation overhaul/LQT Archive 1 on 2015-07-10.

I would suggest splitting all the documentation at ResourceLoader/Default modules into separate pages for each module. That way the module documentation will be more searchable and linkable. We could then replace ResourceLoader/Default modules with something like ResourceLoader/Default modules (draft). Kaldari (talk) 17:39, 17 September 2012 (UTC)

• What is and isn't auto-loaded must not be documented and is not to be relied on. It isn't relevant to anything, and if it, there's something very wrong with the relevant code.
• Wherever it will go, let it be in the Manual namespace
• Make sure we have a consistent page model for each (much like we have consistency for pages of API modules, Database tables and configuration variables).

One interesting point is whether to split up pages by module or by root-level object?

• mw.config and mw.html are not modules, they are part of mediawiki.
• mediawiki.api.edit extends mw.Api.prototype
• $.escapeRE and $.compareObject are both defined in jquery.mwExtension

I propose to document them per module, especially for jQuery plugins that is probably better. That way related code paths are documented on the same page (for they are defined in the same closure, so they have a lot in common already).

From the perspective of a developer, I think the improvement of the documentation is a worthy goal. It's always the last thing on the radar and for an open-source project that just ins't feasible. I think the quality of the documentation and the happiness of the developers are directly correlated. On the surface, I like the idea of integrating the documentation into Mediawiki — maybe a set of docs about the version that you have installed. This gets tricky for updates, though, and I'm sure people will complain that they aren't looking at the most up-to-date version. Even if it's not built-in (and only accessible from the MW-hosted site,) improving the infrastructure to include the JavaScript libraries would be a major win.

I think this all boils down to:

1. improving the in-line documentation in the code
2. working on a solution where this documentation is parsed and displayed to the user in a good way (like the doxygen results)

This project has my full support and I'm willing to work on this, as long as somebody else oversees it (I've got enough going on at work.)

Well it would certainly be nice to have the inline code docs exported to some MW extension, I think the larger problem with docs is lack of large overlaying docs. Docs on individual pieces via doxygen are quite good (imo, some people disagree). Stuff documenting how it all comes together is not so good. (Look at some of the how to write an extension docs, especially for any extensions more complicated than parser tag, gets some input, does some static processing on it, and outputs html. For example, I don't think we even have any docs (other than code comments) on how to write a Media handler extension.