Page MenuHomePhabricator

Update documentation of Reading Web tools (linters, docsyntax, qunit, cucumber/selenium, etc.)
Closed, DuplicatePublic

Description

Problem:

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.

During implementation, it may be discovered that a mediawiki page for all tools (or one per tool) may be the best option here, as opposed to in-repo documentation. If that is the case, then the page(s) should be linked from README.md.

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptAug 18 2016, 4:39 PM
jhobs renamed this task from Update documentation of our tools (linters, docsyntax, qunit, cucumber/selenium, etc.) to Update documentation of Reading Web tools (linters, docsyntax, qunit, cucumber/selenium, etc.).Aug 18 2016, 4:47 PM
jhobs added a comment.EditedAug 18 2016, 4:53 PM

To be clear, I don't think we should be rewriting all of qunit's documentation or anything like that, but we should at least document how to run our tools and link to official docs or tutorials. For tools with more custom implementations (e.g. Mediawiki-Selenium), we should link to more detailed/specific pages.

jhobs triaged this task as Normal priority.Aug 18 2016, 5:18 PM
jhobs moved this task from Incoming to Triaged but Future on the Readers-Web-Backlog board.
Jdlrobson added a subscriber: Jdlrobson.

Isn't this as simple as telling some to run npm test ?
The use of @ignore is supposed to lead a developer to search and ask questions.

I don't see anything actionable here... what do others think?