Add tool to remove condescending language from LORIS documentation #5789

johnsaigle · 2019-11-26T20:16:48Z

Brief summary of changes

How to remove condescending language from documentation

This post outlines why condescending documentation is a bad idea and recommends the alex tool to fix it.

This tool should be helpful as we go forward in creating our documentation on ReadTheDocs.

This PR:

Adds the alex tool to devDependencies
Creates configuration files for this tool
Fixes detected occurrences
Adds alex to our CI pipeline to prevent future issues.

johnsaigle · 2019-11-26T20:17:41Z

.alexrc.yml

@@ -0,0 +1,4 @@
+allow:


These terms are potentially insensitive when used to refer to people, but are helpful in the context of discussing code, e.g.

"invalid data"
"special characters"
"executed a command"

johnsaigle · 2019-11-26T20:18:37Z

README.md

@@ -1,5 +1,6 @@
 # [![Build Status](https://travis-ci.org/aces/Loris.svg?branch=master)](https://travis-ci.org/aces/Loris) LORIS Neuroimaging Platform 

+<!--alex ignore easy-->


The word 'easy' is not helpful to include in code instructions because different tasks are more difficult depending on your background.

However, it's a nice "sales" line in the context of this paragraph

PapillonMcGill

As long as it only generate warning so it won't block as PR.
Nice addition to help us improve text for mishap.

johnsaigle · 2019-12-02T15:14:57Z

I think the warnings do cause build failures actually. I imagine this is configurable.

I'm OK with having it cause build failures because it's quick to fix the errors and I don't think anyone will see them or fix them otherwise (e.g. the JS lint warnings).

PapillonMcGill · 2019-12-02T15:21:37Z

Whaaatt? There are JS lint warning not resolved! You have a good point here.

I guess it wouldn't be difficult to had an exception in case some word are flag even if correct in the context.

johnsaigle · 2019-12-02T15:22:51Z

Yes I agree. And if a word causes problems but we agree it's fine in context then we can add it to the exclude list there.

driusan · 2019-12-02T15:34:49Z

README.md

@@ -1,5 +1,6 @@
 # [![Build Status](https://travis-ci.org/aces/Loris.svg?branch=master)](https://travis-ci.org/aces/Loris) LORIS Neuroimaging Platform 

+<!--alex ignore easy-->


If we need to start hacking up our documents to add machine annotation for this tool, I don't think it should be run automatically as part of Travis and it adds another dependency (both for developers and Travis). We should just be cognizant of the writing style during code review and someone can periodically run the tool to make sure nothing slipped through.

The link that you provided even says that it's intended to flag things for human review, not be used as an absolute rule.

As tempting as it is, you don't want to remove every instance that is flagged by alex or your own search. Because, sometimes, these terms can be present out of necessity or as an attempt to be more welcoming.

(That said, the few changes identified in this PR look good to me.)

Fair enough, I see your point.

Maybe we could assign someone to run the tool during our release process?

Makes sense to me, as long as we remember

that's always precisely the issue. Do we have a new checklist for the release process, that we actually use?

The GitHub project functions as a kind of distributed checklist, I guess.

Anyway I've added a make target for this tool (not included as a part of Travis though) so that it's quick to run the check anyway. Still a step forward.

johnsaigle · 2019-12-02T15:48:00Z

@driusan I added a commit that creates a separate make target for the alex script which also removes it from Travis. I also removed the annotation from README as it's no longer needed to pass Travis.

christinerogers

when just means only (rather than simply) - it should not be stripped.
@johnsaigle i don't think this can be calibrated.

docs/SQLModelingStandard.md

johnsaigle · 2019-12-02T16:48:05Z

@christinerogers I agree with your points. I added some commits just now commits to reword the sentences to be more clear while avoiding the word just. Not that the word is bad in the context but I would like to be able to use the tool without ignoring all cases of the word 'just' or manually adding exceptions to these documents.

docs/SQLModelingStandard.md

christinerogers

Would love to discuss this; I like the idea and I think this should definitely be accompanied by:

Add this link to our Contributing.md in a sentence like "Please note we try to avoid using certain language in our codebase, for details see this list", accompanied by:
a hotlink to the actual list of flagged words, for clarity (e.g. should...)

My $0.02 : We are making taboo a number of words with multiple meanings, not all of which are insensitive, e.g.

modules can simply connect via the API
the file you committed just now
Yes we can find substitutes but why not just flag for validation in the commit process instead of expurgation?

docs/API/LorisRESTAPI.md

christinerogers · 2019-12-02T20:26:01Z

README.Mac.md

@@ -193,7 +193,7 @@ b. Create the file `ext-xdebug.ini` with this command:
 sudo touch /usr/local/etc/php/<your_php_version>/conf.d/ext-xdebug.ini
 ```

-c. Type the following into the `ext-xdebug.ini` file you just created (Note: replace the `zend_extension` path with the correct one on your machine):
+c. Type the following into the `ext-xdebug.ini` file you created (Note: replace the `zend_extension` path with the correct one on your machine):


Again -- this is not the use of just we're looking to expunge...

3 approaches in this case:

Reword the sentence

Suggested change

c. Type the following into the `ext-xdebug.ini` file you created (Note: replace the `zend_extension` path with the correct one on your machine):

c. Type the following into the `ext-xdebug.ini` file created by the above command (Note: replace the `zend_extension` path with the correct one on your machine):

Add an exception like , but Dave asked me not to do this.

Let this be flagged each time the tool is run, generating noise in the report that we have no intention of fixing.

My favourite solution is the 1st.

christinerogers · 2019-12-02T20:27:48Z

docs/SQLModelingStandard.md

- **Date** fields should not just be named “Date”. A
-  **qualifier** like “BoughtDate” or “DateAccepted” should be added as
-  required.  
+- **Date** fields must have **qualifers** (i.e. they should not be named “Date”). A


typo fix:

Suggested change

- **Date** fields must have **qualifers** (i.e. they should not be named “Date”). A

- **Date** fields must have **qualifiers** (i.e. they should not be named “Date”). A

johnsaigle · 2019-12-03T17:54:21Z

Add this link to our Contributing.md in a sentence like "Please note we try to avoid using certain language in our codebase, for details see this list", accompanied by:

I'd be open to a "We use a tool called Alex to help us create accessible and friendly documentation. For more details please view their GitHub repository at [link]"

a hotlink to the actual list of flagged words, for clarity (e.g. should...)

It uses various lists, including ones that contain e.g. racist slurs so I don't think we should do this. A link to the tool is sufficient imo.

modules can simply connect via the API

Is this really so simple though? I have 3 years of experience here and I'm not 100% confident I could explain to someone how to do this. I don't think "simply" adds anything to this sentence and functions at best as a buzzword and at worst as a source of frustration.

I agree with you it's not insensitive but the motivation of the tool aren't limited to words that are disrespectful. it's more subtle as well as more broad than that use case.

Rewording this kind of sentence would be an improvement for this reason.

Yes we can find substitutes but why not just flag for validation in the commit process instead of expurgation?

The idea here is to be able to run the tool and scan for problematic use of language. This tool will generate a report based on everything it thinks is an issue. In some cases these will be false positives, as you've noted and I agree with what you're saying.

At the same time, I'd prefer reword these few instances so that the report contains all signal and no noise when we use it down the line. If the tool is to be useful it shouldn't contain a lot of noise. An example is the ESLint warnings that have been in the repo for years now but nobody cleans up because there's no incentive to do so.

johnsaigle · 2019-12-17T18:43:12Z

@driusan @christinerogers Could you please update your reviews?

driusan · 2019-12-18T14:39:23Z

docs/HelpStyleGuide.md

@@ -66,3 +66,6 @@ This means using more direct language and tone to get information across to the
 * Break up large blocks of text. It's more visually pleasing and less intimidating.

 For more information, including research studies conducted, on the use and value of Plain Language, please see [this article](https://www.nngroup.com/articles/plain-language-experts/) and feel free to browse the rest of this website for further helpful details, tips, and tricks. 
+
+In addition to the above guidelines, we use [Alex JS](https://github.com/get-alex/alex)$
+to help us create documentation that is friendly and accessible.


I don't think this advertisement for a third party tool belongs here.

@christinerogers asked that it be mentioned somewhere in the documentation. It felt most relevant to include it in a document outlining our documentation style.

I don't think it's an advertisement so much as just a fact about the project, similar to saying "we use phan to make sure our code doesn't suck"

"and if you want to know why we might change particualr language you use, here's the info... "

I feel that providing the link to the tool implies indicates that that's the place to find info.

driusan

Even if I didn't have my last comment, this can't be merged because there's no Travis run for it.

Makefile

Changes addressed; travis is being run

driusan

last minor nitpick

driusan · 2020-01-16T16:25:47Z

CONTRIBUTING.md

@@ -76,6 +76,8 @@ using the command `make checkstatic` and fix any resulting errors. Otherwise,
 would affect the data or custom code of a study - document this in your pull 
 request description and tag it with **Caveat for Existing Projects**. 
 This helps us to document our release notes.
+* In addition to the above guidelines, we use [Alex JS](https://github.com/get-alex/alex) 


This still shouldn't be advertising external tools. The HelpStyleGuide mention of it is fine, but for CONTRIBUTING.md the contributor should just need to know that they can run make checklanguage to verify the documentation.

Changes incorporated

johnsaigle commented Nov 26, 2019

View reviewed changes

PapillonMcGill previously approved these changes Dec 2, 2019

View reviewed changes

driusan requested changes Dec 2, 2019

View reviewed changes

johnsaigle dismissed PapillonMcGill’s stale review via cf36058 December 2, 2019 15:47

christinerogers requested changes Dec 2, 2019

View reviewed changes

docs/SQLModelingStandard.md Show resolved Hide resolved

docs/SQLModelingStandard.md Show resolved Hide resolved

PapillonMcGill reviewed Dec 2, 2019

View reviewed changes

docs/SQLModelingStandard.md Outdated Show resolved Hide resolved

johnsaigle requested review from christinerogers and driusan December 2, 2019 20:28

christinerogers requested changes Dec 2, 2019

View reviewed changes

johnsaigle added the State: Needs rebase PR that needs to be rebased to proceed (conflicts, wrong branch...) label Dec 3, 2019

johnsaigle changed the base branch from major to master December 3, 2019 17:41

johnsaigle removed the State: Needs rebase PR that needs to be rebased to proceed (conflicts, wrong branch...) label Dec 3, 2019

johnsaigle mentioned this pull request Dec 17, 2019

Document LORIS automated testing #5859

Merged

johnsaigle requested a review from christinerogers December 17, 2019 17:23

christinerogers approved these changes Dec 18, 2019

View reviewed changes

driusan reviewed Dec 18, 2019

View reviewed changes

driusan previously requested changes Dec 18, 2019

View reviewed changes

driusan reviewed Dec 18, 2019

View reviewed changes

Makefile Show resolved Hide resolved

PapillonMcGill reviewed Jan 6, 2020

View reviewed changes

Makefile Show resolved Hide resolved

PapillonMcGill approved these changes Jan 6, 2020

View reviewed changes

johnsaigle requested a review from driusan January 8, 2020 18:27

johnsaigle added State: Needs rebase PR that needs to be rebased to proceed (conflicts, wrong branch...) and removed State: Needs rebase PR that needs to be rebased to proceed (conflicts, wrong branch...) labels Jan 8, 2020

driusan previously requested changes Jan 16, 2020

View reviewed changes

johnsaigle added 9 commits February 7, 2020 17:26

Add tool to remove condescending language from documentation

d9bc2a6

Add alex configuration files

21c5ec6

add alex check to static analysis

23f731c

Add to makefile

ca95336

Fix ocurrences

68ae51f

Make new make target for alex

8c6e181

Add note about alex in style guide [ci skip]

9586e02

Add a note to CONTRIBUTING

4c7a9ab

Change wording of CONTRIBUTING

cca1f23

johnsaigle requested a review from driusan February 7, 2020 22:27

driusan merged commit b95740f into aces:master Feb 13, 2020

ridz1208 added this to the 23.0.0 milestone Feb 25, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add tool to remove condescending language from LORIS documentation #5789

Add tool to remove condescending language from LORIS documentation #5789

johnsaigle commented Nov 26, 2019

johnsaigle Nov 26, 2019

johnsaigle Nov 26, 2019

PapillonMcGill left a comment

johnsaigle commented Dec 2, 2019

PapillonMcGill commented Dec 2, 2019

johnsaigle commented Dec 2, 2019

driusan Dec 2, 2019

johnsaigle Dec 2, 2019

driusan Dec 2, 2019

christinerogers Dec 2, 2019

johnsaigle Dec 2, 2019

johnsaigle commented Dec 2, 2019

christinerogers left a comment

johnsaigle commented Dec 2, 2019

christinerogers left a comment •

edited

Loading

christinerogers Dec 2, 2019

johnsaigle Dec 3, 2019 •

edited

Loading

christinerogers Dec 2, 2019

johnsaigle commented Dec 3, 2019

johnsaigle commented Dec 17, 2019

driusan Dec 18, 2019

johnsaigle Dec 18, 2019

christinerogers Dec 20, 2019

johnsaigle Jan 6, 2020

driusan left a comment

driusan left a comment

driusan Jan 16, 2020

johnsaigle Jan 20, 2020

		@@ -1,5 +1,6 @@
		# [![Build Status](https://travis-ci.org/aces/Loris.svg?branch=master)](https://travis-ci.org/aces/Loris) LORIS Neuroimaging Platform

		<!--alex ignore easy-->

	c. Type the following into the `ext-xdebug.ini` file you created (Note: replace the `zend_extension` path with the correct one on your machine):
	c. Type the following into the `ext-xdebug.ini` file created by the above command (Note: replace the `zend_extension` path with the correct one on your machine):

	- Date fields must have qualifers (i.e. they should not be named “Date”). A
	- Date fields must have qualifiers (i.e. they should not be named “Date”). A

Add tool to remove condescending language from LORIS documentation #5789

Add tool to remove condescending language from LORIS documentation #5789

Conversation

johnsaigle commented Nov 26, 2019

Brief summary of changes

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PapillonMcGill left a comment

Choose a reason for hiding this comment

johnsaigle commented Dec 2, 2019

PapillonMcGill commented Dec 2, 2019

johnsaigle commented Dec 2, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnsaigle commented Dec 2, 2019

christinerogers left a comment

Choose a reason for hiding this comment

johnsaigle commented Dec 2, 2019

christinerogers left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnsaigle Dec 3, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnsaigle commented Dec 3, 2019

johnsaigle commented Dec 17, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

driusan left a comment

Choose a reason for hiding this comment

driusan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

christinerogers left a comment •

edited

Loading

johnsaigle Dec 3, 2019 •

edited

Loading