Jump to content

Topic on Talk:Requests for comment/Documentation overhaul

DanielRenfro (talkcontribs)

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.)

Bawolff (talkcontribs)

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.

Reply to "Full support"