Fixed #30573 -- Rephrased documentation to avoid words that minimise the involved difficulty. by rixx · Pull Request #11482 · django/django

rixx · 2019-06-17T15:00:19Z

Obviously (heh.) this patch does not remove all occurrences of the words
in question. Rather, I went through all of the occurrences of the words
listed below, and judged if they a) suggested the reader had some kind
of knowledge/experience, and b) if they added anything of value
(including tone of voice, etc). I left most of the words alone. I looked
at the following words:

simply/simple
easy/easier/easiest
obvious/obviously
just
merely
straightforward
ridiculous

Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea.

Ticket link: https://code.djangoproject.com/ticket/30573

docs/faq/contributing.txt

carltongibson · 2019-06-17T15:17:42Z

Hey @rixx. Thanks for this. (Can't remember what I actually said, but 👍 🙂)

Obviously...

Perfect. 😀

@claudep, @felixxm makes a good point on the ticket about creating work for the translation teams (so not to backport). Tim often would mention the need for re-translations too. Can I ask, what's the general maxim there? And, for me, this patch seems positive and in line with what we aim for generally, so is it reasonable, without putting too much burden on our current volunteers? (I'm just not sure of the state of play. Thank you!)

claudep

From a translator point of view, please avoid backporting to current docs. As for the wording, I'm not fluent enough in English to judge.

rixx · 2019-06-17T16:25:04Z

Tim often would mention the need for re-translations too. Can I ask, what's the general maxim there? And, for me, this patch seems positive and in line with what we aim for generally, so is it reasonable, without putting too much burden on our current volunteers?

I have to admit that I hadn't thought of the additional burdon for translators. If you judge this PR to have an unhelpful ratio of effort for translators as opposed to its usefulness, we can definitely decide to close it.

carltongibson · 2019-06-17T16:43:41Z

I think the sentiment, that we eliminate the "just" and "obviously" and so on is right. And it can't be that we can't make improvements — but knowing the work it involves is helpful to judge. Obviously (🙂) there's no hard line; I was fishing for rule-of-thumb guidance... (Thanks again.)

claudep · 2019-06-17T19:28:40Z

If this is really improving the docs (not simple nit-picking), you should do it. I just say that the stable docs should only be changed for real errors, because between the push and the translations going on-line, there is a gap of ~1 month where those strings appear untranslated.

carltongibson · 2019-06-17T19:45:11Z

OK, thanks @claudep. That's a good guiding principle.

adamchainz

Reviewed about 20% so far... 😱

In general a great improvement 👍

docs/faq/general.txt

docs/faq/contributing.txt

docs/faq/usage.txt

docs/howto/custom-model-fields.txt

docs/howto/static-files/deployment.txt

docs/howto/windows.txt

docs/internals/contributing/bugs-and-features.txt

docs/internals/contributing/committing-code.txt

adamchainz

Second review, next file to review is docs/topics/db/search.txt

docs/internals/contributing/writing-code/submitting-patches.txt

docs/internals/contributing/writing-code/unit-tests.txt

docs/internals/contributing/writing-documentation.txt

docs/intro/contributing.txt

docs/topics/class-based-views/mixins.txt

docs/topics/db/managers.txt

docs/topics/db/optimization.txt

adamchainz

Done 😅

docs/topics/db/transactions.txt

docs/topics/email.txt

docs/topics/forms/formsets.txt

docs/topics/forms/index.txt

docs/topics/migrations.txt

docs/topics/pagination.txt

docs/topics/performance.txt

docs/topics/serialization.txt

rixx · 2019-07-07T00:46:17Z

I think I addressed all your review comments by resolving them, except for two which I replied to. Thank you so much for reviewing this little monster!

adamchainz · 2019-07-07T12:25:46Z

Nice work!

rixx · 2019-07-07T19:09:44Z

Right, got the rebase conflict addressed, too, so this is looking good, pending further review :)

adamchainz

I'm approving but if you want to leave for a bit to see if anyone else has the heart to read all this, fair enough :)

rixx · 2019-07-07T19:36:36Z

I'm completely happy with your review, I just saw that there was "1 pending reviewer" in the GitHub interface, so I wasn't sure how this was going to proceed. I don't need a second review ;)

carltongibson · 2019-07-08T07:41:38Z

...just saw that there was "1 pending reviewer"...

I want to go through this, so it's that's me. It's on the list for this week. 🙂

wreis

++

carltongibson

Hi @rixx.

Just before diving into the individual changes, I think, having gone to this effort, we should add a paragraph/sentence to writing-documentation.txt in the Writing style section, saying to avoid using simple etc in this way. What do you think?

rixx · 2019-08-13T21:57:19Z

Hi @rixx.

Just before diving into the individual changes, I think, having gone to this effort, we should add a paragraph/sentence to writing-documentation.txt in the Writing style section, saying to avoid using simple etc in this way. What do you think?

Absolutely, I added a change like that. Feel free to correct the phrasing, as always.

carltongibson · 2019-09-05T08:02:06Z

Right, roll-up sleeves...

I rebased and pulled the Style suggestion into a separate commit cf9e66fe58e198faf647a07b2ab5625dba417985. (@felixxm We could pull that in already no?)

I'll go through the text changes one-by-one now. (Given how many changes there are, I think I'll push an Edits commit to allow review of any suggestions... — incoming. 🙂)

felixxm · 2019-09-05T08:16:28Z

@carltongibson Sure, merged and backported (I fixed one typo).

carltongibson · 2019-09-05T08:22:24Z

Thanks @felixxm!

carltongibson

Right. Wowser. That took a while. 😅

I've pushed edits. @rixx — please have a look.

I felt a bit sorry for "Just" and "Simple" — they're not always minimisers. Sometimes they have import. I've restored those I felt essential. I've let some go, thinking that leaning towards being strict is fine now, as they'll leak back in over time, and we've probably over-used in the past.
There were a few purely cosmetic re-wraps. These were correct, AFAICS, so I left them, not having the energy to pull them out.
I reverted the man page change as @felixxm will do that he branches for 3.0.

Thank you for your effort here! 🥇

@felixxm: This is good to go for me (with a squash). There may be one or two little regressions I've missed, but overall the patch is good — I think it should be much more approachable for folks (like me) who aren't entirely convinced that e.g. writing custom migration operations is simple 🙂. If you have bandwidth to review before we branch stable/3.0.x then super. If not I think we should take it anyway.

docs/ref/csrf.txt

rixx · 2019-09-05T14:41:12Z

@carltongibson Thank you very much for your review! Apart from one typo, your changes look fine to me.

I also sympathised with "just" and "simple", and left many of them in place, but I appreciate your reverts. I guess after some time staring at the same words, I leaned too much on the side of removal. Regarding the cosmetic rewraps: I tried to remove all of them and just rewrap paragraphs ends following my changes. If you'd like me to, I can check the PR again and see what should be reverted?

carltongibson · 2019-09-05T15:05:11Z

Typo fixed. 👍

Regarding the cosmetic rewraps: I tried to remove all of them and just rewrap paragraphs ends following my changes. If you'd like me to, I can check the PR again and see what should be reverted?

If you have energy... They weren't incorrect so I left them. At this point I'd be happy to see them left. (@felixxm may have an opinion, which he'll state if he does 🙂)

...I guess after some time staring at the same words...

Yes. 😀

Much effort. Hard to do. Hard to review.

You've done a great job here.

…the involved difficulty. This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.

felixxm · 2019-09-06T11:55:45Z

Thanks y'all 🌟

rixx force-pushed the ticket_30573 branch from 2f135aa to ea84416 Compare June 17, 2019 15:03

carltongibson self-requested a review June 17, 2019 15:05

felixxm reviewed Jun 17, 2019

View reviewed changes

docs/faq/contributing.txt Outdated Show resolved Hide resolved

carltongibson requested a review from claudep June 17, 2019 15:13

claudep reviewed Jun 17, 2019

View reviewed changes

rixx force-pushed the ticket_30573 branch 2 times, most recently from b3cbba8 to d322d9f Compare June 17, 2019 16:24

rixx force-pushed the ticket_30573 branch from d322d9f to 1bd2c75 Compare June 17, 2019 16:30

adamchainz reviewed Jun 25, 2019

View reviewed changes

rixx force-pushed the ticket_30573 branch from 1bd2c75 to 5d3d2c3 Compare June 25, 2019 16:46

adamchainz reviewed Jun 27, 2019

View reviewed changes

rixx force-pushed the ticket_30573 branch 2 times, most recently from cd535e4 to 4c497a4 Compare July 7, 2019 00:46

rixx force-pushed the ticket_30573 branch from 4c497a4 to 52f74b3 Compare July 7, 2019 15:56

adamchainz approved these changes Jul 7, 2019

View reviewed changes

wreis approved these changes Jul 8, 2019

View reviewed changes

carltongibson reviewed Jul 8, 2019

View reviewed changes

rixx force-pushed the ticket_30573 branch from 52f74b3 to bf924b8 Compare August 3, 2019 05:26

rixx force-pushed the ticket_30573 branch from bf924b8 to 2963987 Compare August 13, 2019 20:27

rixx force-pushed the ticket_30573 branch from 2963987 to 1834c52 Compare August 13, 2019 21:57

carltongibson force-pushed the ticket_30573 branch 2 times, most recently from fafe9ae to 085156b Compare September 5, 2019 07:59

felixxm force-pushed the ticket_30573 branch from 085156b to cfa59eb Compare September 5, 2019 08:17

carltongibson force-pushed the ticket_30573 branch from cfa59eb to 4fd0cf6 Compare September 5, 2019 11:01

carltongibson approved these changes Sep 5, 2019

View reviewed changes

rixx commented Sep 5, 2019

View reviewed changes

docs/ref/csrf.txt Outdated Show resolved Hide resolved

carltongibson force-pushed the ticket_30573 branch from 4fd0cf6 to c1ba079 Compare September 5, 2019 15:02

felixxm changed the title ~~Fixed #30573 -- Remove simple/easy/etc from documentation~~ Fixed #30573 -- Rephrased documentation to avoid words that minimise the involved difficulty. Sep 6, 2019

felixxm force-pushed the ticket_30573 branch from c1ba079 to 4a954cf Compare September 6, 2019 11:34

felixxm merged commit 4a954cf into django:master Sep 6, 2019

rixx deleted the ticket_30573 branch September 6, 2019 12:37

adamchainz mentioned this pull request May 1, 2020

Refs #30573 -- Rephrased "Of Course" and "Obvious(ly)" in documentation and comments. #12838

Merged

simonw mentioned this pull request Nov 12, 2020

Sweep documentation for words that minimize involved difficulty simonw/datasette#1089

Closed

Uh oh!

Conversation

rixx commented Jun 17, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

carltongibson commented Jun 17, 2019

Uh oh!

claudep left a comment

Choose a reason for hiding this comment

Uh oh!

rixx commented Jun 17, 2019

Uh oh!

carltongibson commented Jun 17, 2019

Uh oh!

claudep commented Jun 17, 2019

Uh oh!

carltongibson commented Jun 17, 2019

Uh oh!

adamchainz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adamchainz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adamchainz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rixx commented Jul 7, 2019

Uh oh!

adamchainz commented Jul 7, 2019

Uh oh!

rixx commented Jul 7, 2019

Uh oh!

adamchainz left a comment

Choose a reason for hiding this comment

Uh oh!

rixx commented Jul 7, 2019

Uh oh!

carltongibson commented Jul 8, 2019

Uh oh!

wreis left a comment

Choose a reason for hiding this comment

Uh oh!

carltongibson left a comment

Choose a reason for hiding this comment

Uh oh!

rixx commented Aug 13, 2019

Uh oh!

carltongibson commented Sep 5, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

rixx commented Jun 17, 2019 •

edited

Loading

carltongibson commented Sep 5, 2019 •

edited

Loading