Skip to content

Docs: better explanation for docs-lint errors

Problem to solve

Most of the docs-lint error outputs do not explain what's wrong with the current syntax. We should either provide a better explanation or at least link to the style guide so the MR author can easily identify and fix their content.

As an example, see this output:

Screen_Shot_2020-10-30_at_16.06.39

For this result in !45588 (comment 435222040), @phikai says:

As some general feedback - it'd be nice if the errors from Vale could tell me what to do or at least where to go look.

I've seen lots of feedback like this lately, and I agree with all of them. Even for us, TWs, sometimes is hard to interpret the linter outputs, and we all know (most of) the rules by heart.

Proposal

  • Only lint for things that matter (that's my pov, but that's me).
  • Improve linter errors output to provide guidance for the contributor.

Who can address the issue

tw-testing committee. cc/ @aqualls @marcel.amirault (please take a look? Tnx!)