devtools-docs

devtools-docs copied to clipboard

We are getting a lot of false-positives from Proofreader (e.g. https://travis-ci.org/GoogleChrome/devtools-docs/builds/50876713 ). In order to fix that we have to:

• add missing words to devtools-docs.dic and
• decide on write-good settings.

Currently, all write-good checks are being performed:

• passive Checks for passive voice.
• illusion Checks for lexical illusions – cases where a word is repeated.
• so Checks for so at the beginning of the sentence.
• thereIs Checks for there is or there are at the beginning of the sentence.
• weasel Checks for "weasel words."
• adverb Checks for adverbs that can weaken meaning: really, very, extremely, etc.
• tooWordy Checks for wordy phrases and unnecessary words
• cliches Checks for common cliches

Individual checks can be easily deactivated using proofreader's config file. I just need to know which we should keep. Opinions?

I think the only thing we should turn off is whatever is taking keyboard shortcuts and trying to make those into words. Other than that, the noise from the builds are really accurate and good information to fix the next time that content is touched.

In fact, I agree with Proofreader here. These keyboard shortcuts (e.g. "Control+click" -> Controlling) should be wrapped in <span class="kbd">.

As for the write-good settings, IMO tooWordy is useless most of the time e.g.

Evaluate your site's performance[...] "Evaluate" is wordy or unneeded

[...]enforces a minimum delay in connection[...] "minimum" is wordy or unneeded

Oh, it is because those aren't wrapped in elements like they should be! Maybe a linter could be built to try and detect that?

On tooWordy, I think I'd like to see how this reacts to other pages as well and see how verbose it gets. I find that one could be very useful in many pages (since that is what I hit most with hemmingway.)

@btford wanted to pull you into this. we have write-good hooked up to our PRs on this repo. it's pretty rad. https://travis-ci.org/GoogleChrome/devtools-docs/builds/50876713

But as you can see we also get a LOT of reports incoming and some are probably false positives.

Do you have any advice for how we can engage with writegood well with a large corpus?

Ohh, this is interesting. I hadn't considered using this in a CI environment.

I think it would be easy to fix some of the passive voice ones in write-good itself by white listing certain constructions. Long term, a parts-of-speech identifier would provide more accuracy, but at a cost of run-time speed.

For now, you could check in a list of allowed warnings and diff the output of write-good against that list. This would make catching new style issues easy.

@btford thank you for input, it's much appreciated!

list of allowed warnings

You are saying that we should create a list of specific write-good warnings that should be ignored, right? I think it's a good start, but I'm worried that most of these warnings depend heavily on the context e.g. we can't assume that "minimum" is wordy or unneeded will always be an invalid suggestion, can we?

Yea, this "wordy" thing needs to be chunked quick until we get some kind of fix in place. I thought it may not be a big deal, but calling this out in this context is a bad sign...

"evaluate" is wordy or uneeded when it is nothing but needed.

"Only" can weaken meaning

Weaken meaning may need to be looked at as well. Not sure what is causing this, but it is literally the functionality. "Errors Only", "Logs Only", "Info only", etc. If we could even somehow target these usages out that would be great. Just another thing to fill-in-as-we-go if possible.