Consider removing words that shouldn't be used in educational writing from the docs (simply, easily, just)

[robwierzbowski]

Pointing out how "simple", "obvious", or "easy" something is can have the opposite-of-intended effect. If a person doesn't understand the 'simple' code, the project can seem inaccessible. "I don't understand this easy thing. I guess I just don't get it like other people do." A good resource on words to avoid is https://css-tricks.com/words-avoid-educational-writing/. Some that appear often in the Gatsby documentation are "simply", "easily", and "just (do x)".

For example, in the Plugins documentation:

Plugins are just Node.js packages meaning you install them like anything else in node using NPM.

Then in your site’s gatsby-config.js you simply add gatsby-transformer-json to the plugins array like:

If I wasn't familiar with node modules, or if I had any trouble or experienced a bug when adding something to the plugins array I might feel especially stupid for not "getting" an easy thing. IMO it's better to show something is easy than to say it is!

These could be rewritten to be more direct, not assume ease, but still be friendly:

Plugins are Node.js packages. You can install them with NPM.

Then, in your site’s gatsby-config.js add gatsby-transformer-json to the plugins array:

I removed this type of language from the Vue documentation, but don't currently have time to try the same here. Would you consider cleaning up some of the language that assumes ease?

[calcsam]

Thanks for pointing this out. Anyone willing to take this on?

[benjaminhoffman]

Thanks @robwierzbowski !

Besides "simply", "easily", and "just (do x)", are there any other similar words? Let's catalogue them in this thread so we can do the necessary cleanup in one pass.

[robwierzbowski]

There’s a good list in the article I linked. Side note, I found when revising Vue’s Docs things were made more clear by removal of words, as opposed to substitution. Short and sweet.

Thanks! I appreciate you being so proactive and open to suggestion.

[robwierzbowski]

I'll add more language you may want to look at here, as I continue to read the docs.

• "as the name suggests" (assumes conclusion, and probably a little unnecessary)

[benjaminhoffman]

I guess this is a start... can you guys give this a quick review? #3241

[KyleAMathews]

@benjaminhoffman's issue pretty much fixed this. Let's keep an eye out for this sort of language!

[benjaminhoffman]

There's actually still a bunch more but we can tackle them overtime. Here is another stab at it: #3523

[KyleAMathews]

Good take on this

"Coding is hard" will discourage some people from attempting it.

"Coding is easy" will discourage some people who are attempting it and finding it challenging.

Alternative: Learning to code is a never ending journey with a set of challenges and delights unique to each person.

https://twitter.com/aprilwensel/status/953387594783506433

[shannonbux]

Woo look at this content editor!

[KyleAMathews]

@shannonbux nice! Yeah, we should totally add this. I'll create an issue for it.