From T140352#2496343:
> D@jhobs pointed out various problems with our documentation things:on.
= Config variables
>
> * Config variables are poorly documented. It's currently hard to tell exactly what they do and, as we've recently seen with wikidata descriptions, having a vague idea is not good enough. The new feature logging system should help with this, but let's find an easy way to attach config variables to features in documentation.
[] Check that all config variables defined in extension.json are documented in README.md
= Getting started
> * We don't really document our process for making contributions very well. We have sections in README.md that explain tests and commits, but some aren't especially well-written. As an example, I tried following the instructions for running tests and was immediately met with an error and nowhere to go for troubleshooting (if I were a first-time volunteer who didn't know about #wikimedia-mobile on IRC). In order to help onboard new devs and encourage volunteer contributions, I think we should refactor the top of README.md to be a bit more "how-to", or have another document in the repo to describe how to get started. If we decide on a new document I'd recommend CONTRIBUTIONS.md or CONTRIBUTIONS.mediawiki, the latter of which could correspond to a page on mediawiki.org.
[] Add CONTRIBUTIONS.md
> * As a contributor, if I'm not sure of how to properly document a method (syntax, format, etc.), my only real option is to open similar files and hope they have the info I need. For example, I've never known what @ignore does and can only assume it forces the linter to skip the method or something, which is odd as I've seen it on multiple important methods. For me, the answer is as simple as "ask a team member," but volunteers would be much more lost. We should more easily expose documentation -- be it links to official websites or our own documentation -- for libraries, testing frameworks, linters, and any other tools we use. Another example of this is our Selenium tests. We use a custom mediawiki implementation of Selenium, which is already not the most well-known framework. Googling for answers when writing a browser test for our extensions hardly provides useful info and will often just lead people to forego writing tests altogether.
> * There are several undocumented methods, parameters, return values, etc. within our extensions, as well as just poorly documented ones (https://github.com/wikimedia/mediawiki-extensions-MobileFrontend/blob/master/includes/api/ApiMobileView.php#L45-L243,[] Move anything developer specific to CONTRIBUTIONS.md. for example). A clean sweep is probably overdueREADME.md should be for sysadmins. This bullet point alone could translate to an epic with subtasks for checking/fixing documentation for every feature.
>At the top of the README add a line "For those interested in contributing to the codebase please see CONTRIBUTIONS.md
>I'm sure there's more, but this is what I've found for now. In general I just think it's very easy for someone to feel lost within our code rather than knowing exactly where to look to fix Problem X, even if we mark Problem X as an Easy task.[] Review and update setup instructions in the new CONTRIBUTIONS.md file
I suspect that T141087 will help this task a lot but,> * As a contributor, if I'm not sure of how to properly document a method (syntax, format, etc.), my only real option is to open similar files and hope they have the info I need. For example, I've never known what @ignore does and can only assume it forces the linter to skip the method or something, which is odd as I've seen it on multiple important methods. For me, the answer is as simple as "ask a team member," but volunteers would be much more lost. We should more easily expose documentation -- be it links to official websites or our own documentation -- for libraries, testing frameworks, linters, and any other tools we use. Another example of this is our Selenium tests. We use a custom mediawiki implementation of Selenium, which is already not the most well-known framework. as @phuedx points out in said task,Googling for answers when writing a browser test for our extensions hardly provides useful info and will often just lead people to forego writing tests altogether.
[] Link to suitable documentation for jsduck and Selenium in getting started instructions. documentation changes should be run in parallel.Use relevant mediawiki.org wiki pages where possible.