Change Details

@jhobs pointed out various problems with our documentation. = 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 [] Move anything developer specific to CONTRIBUTIONS.md. README.md should be for sysadmins. At the top of the README add a line "For those interested in contributing to the codebase please see CONTRIBUTIONS.md [] Review and update setup instructions in the new CONTRIBUTIONS.md file [] Add instructions that help a new contributor with only a fresh vagrant instance and Gerrit account to drive a change from start to finish, including running tests. > * 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. [] Link to suitable documentation for jsduck and Selenium in getting started instructions. Use relevant mediawiki.org wiki pages where possible.

@jhobs pointed out various problems with our documentation. = 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 CONTRIBUTING.md or CONTRIBUTING.mediawiki, the latter of which could correspond to a page on mediawiki.org. [] Add CONTRIBUTING.md [] Move anything developer specific to CONTRIBUTING.md. README.md should be for sysadmins. At the top of the README add a line "For those interested in contributing to the codebase please see CONTRIBUTING.md [] Review and update setup instructions in the new CONTRIBUTING.md file [] Add instructions that help a new contributor with only a fresh vagrant instance and Gerrit account to drive a change from start to finish, including running tests. > * 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. [] Link to suitable documentation for jsduck and Selenium in getting started instructions. Use relevant mediawiki.org wiki pages where possible.

@jhobs pointed out various problems with our documentation. = 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 CONTRIBUTIONSNG.md or CONTRIBUTIONSNG.mediawiki, the latter of which could correspond to a page on mediawiki.org. [] Add CONTRIBUTIONSNG.md [] Move anything developer specific to CONTRIBUTIONSNG.md. README.md should be for sysadmins. At the top of the README add a line "For those interested in contributing to the codebase please see CONTRIBUTIONSNG.md [] Review and update setup instructions in the new CONTRIBUTIONSNG.md file [] Add instructions that help a new contributor with only a fresh vagrant instance and Gerrit account to drive a change from start to finish, including running tests. > * 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. [] Link to suitable documentation for jsduck and Selenium in getting started instructions. Use relevant mediawiki.org wiki pages where possible.