Linguist: Update GitHub.com's User Documentation

[pchaigno]

The current documentation for code blocks is a bit misleading:

We use Linguist to perform language detection and syntax highlighting.

Given the number of issues opened for highlighting bugs that usually don't belong here, I think it would be worth changing the wording to clarify that Linguist only takes care of language detection and point to the list of grammars for syntax highlighting issues.

I'm opening the issue here instead of reporting to [email protected] directly so that we can discuss it if necessary.

/cc @lildude

[pchaigno]

What about this sentence instead?

We use Linguist to perform language detection and a number of third-party grammars for syntax highlighting.

@lildude Should I ping someone else inside GitHub regarding this (someone from the doc team maybe)?

[Alhadis]

Try this:

We use Linguist to perform language detection and select language grammars to provide syntax highlighting.

[pchaigno]

@Alhadis I changed the subject for the syntax highlighting phrase to make it crystal clear that Linguist doesn't perform syntax highlighting (and the grammars are not maintained by GitHub). I'm worried your proposed sentence might still give that impression to some people.
What did you want to improve specifically? Was it "a number of" that sounded weird? Or "third-party grammars" maybe?

[Alhadis]

The "number of" part did sound a little awkward, yes. What about

We use Linguist to perform language detect and to select third-party grammars for syntax highlighting

Basically, I feel the "select" verb communicates Linguist's relationship to grammars a bit better.

[pchaigno]

Yep, that sounds fine!

As a side question: do you know why "a number of" sounds weird?

[Alhadis]

Not so much "weird", merely superfluous. =) It adds no new information for the reader.

Conciseness and clarity go hand-in-hand, I've learned. Keeping documentation short and digestible also gives less excuses for lazy or impatient readers.

[lildude]

@lildude Should I ping someone else inside GitHub regarding this (someone from the doc team maybe)?

I can do it. Once we've finalised on the wording, I'll open the PR.

[pchaigno]

I think we're settled on:

We use Linguist to perform language detection and to select third-party grammars for syntax highlighting.

[lildude]

PR raised with the ☝️ wording.

[pchaigno]

Thanks @lildude, @Alhadis, and @emilyistoofunky!