w3c
Feedback: Unclear/inexact "Bug reports" section
The How to Provide Feedback For the W3C Markup Validator page ends with a Bug reports section, which reads:
W3C tracks bug reports on the validator through the GitHub repositories where the code is maintained. Developers and other technical users can log bug reports and feature suggestions directly. If you are not familiar with issue tracking systems in general, send your feedback to the mailing list and someone on the W3C Validator Team will take care of logging your issue as appropriate.
There are two distinct repositories where issues can be filed; if you're not sure which to use, pick the first one and we will take care of transferring it if necessary:
- the (X)HTML validator which is used to validate HTML4 and XHTML documents, and provides the shared front-end for markup validation;
- the NU validator which is the most actively maintained project, used to validate HTML5 / HTML LS documents.
Before you enter a new bug, we strongly encourage you to check that it is not yet in the list of opened issues.
There are a bunch of issues here, which this reports in bulk:
- "bug reports" are not tracked. bugs are.
- The section appears to be about all issues (including at least missing features), but is only titled "Bug reports".
- A space is missing in "HTML4".
- "NU" is written fully capitalized, as if it was acronym.
- "HTML5 / HTML LS documents" is unclear; even I, a senior web developer who has learned HTML nearly 3 decades ago, did not immediately understand.
- The Markup Validator is called "the (X)HTML validator".
- #2 does not indicate handling of CSS and SVG validation.
- It suggests the Markup Validator is the one handling XHTML5.
- "check that it is not yet in the list of opened issues" is unclear.
- The description does not clearly explain whether the 2 repositories track issues with the (FOSS) products, with the W3C services which offer them, or both. I would gather from that comment that #2 only tracks the product, but the Markup Validator’s repository suggests it is about the service.
- The enumeration markers (numbers) are in the left margin.
- This suggests readers unsure about which repository is appropriate to report against the first, which is likely to cause duplicate tickets.
The following solves the first 8 and a few more linguistic details:
<h3 id="bugreport">Issue tracking</h3>
<p>
W3C tracks validator issues through the GitHub repositories where the code is maintained. Developers
and other technical users can report problems directly. If you are not familiar with issue tracking systems in general,
send your feedback to the <a href="#mailinglist">mailing list</a>
and―if necessary―someone on the W3C Validator Team will take care of filing a ticket as appropriate.
</p>
<p>There are two distinct repositories where issues can be filed; if you're not sure which to use, pick the first one and we will take care of transferring it if necessary:</p>
<ol>
<li><a href="https://github.com/w3c/markup-validator">the Markup Validator</a>, which is used to validate HTML 4 and XHTML 1 documents, and provides the shared front-end for markup validation;</li>
<li><a href="https://github.com/validator/validator/">the Nu validator</a>, the main project, used to validate modern HTML documents (version 5 or later) documents, CSS stylesheets and SVG images.</li>
</ol>
<p>Before you report an issue, we strongly encourage you to check that it is not already reported.</p>
For point #12, I suggest directing readers to the IRC channel for guidance. As for #7, I do not know how the validators are implemented and am not sure what should be done about CSS, which appears to have its own repository. My understanding is that this code is copied in the Nu validator, so that it would not be incorrect to report CSS Validator issues against the Nu validator.
