Opened 5 months ago

Closed 2 months ago

#30573 closed Cleanup/optimization (fixed)

Don't assume that things are "easy"/"obvious"/"simple" in the docs.

Reported by: Tobias Kunze Owned by: Tobias Kunze
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

Telling people in documentation that something is "easy" or "obvious" when it isn't to them is very frustrating: It implies that the reader should have a level of understanding they don't have, and doesn't add anything of value in return. There are many occurrences of more-or-less obvious instances of this pattern in the Django docs, and I'd like to reduce the occurrence of this pattern.

Change History (8)

comment:1 Changed 5 months ago by Tobias Kunze

Has patch: set

comment:2 Changed 5 months ago by felixxm

Summary: Don't assume that things are "easy"/"obvious"/"simple" in the docsDon't assume that things are "easy"/"obvious"/"simple" in the docs.
Triage Stage: UnreviewedAccepted

Sound like a good idea.

PR

Note: IMO we shouldn't backport this patch because it will create a huge amount of work for translators.

comment:3 Changed 3 months ago by Tapasweni Pathak

Hello folks: I would like PRing for the ticket? Is the PR merged?

comment:4 Changed 3 months ago by felixxm

Owner: changed from nobody to Tobias Kunze

Fix is already submitted, you should rather search for tickets without patches and owners.

comment:5 Changed 2 months ago by Mariusz Felisiak <felisiak.mariusz@…>

In ed2d411:

Refs #30573 -- Noted to avoid "simple" & co. in Writing Style guide.

Co-authored-by: Tobias Kunze <r@…>

comment:6 Changed 2 months ago by Mariusz Felisiak <felisiak.mariusz@…>

In dee22a0:

[2.2.x] Refs #30573 -- Noted to avoid "simple" & co. in Writing Style guide.

Co-authored-by: Tobias Kunze <r@…>

Backport of ed2d411aa84efc76baba3adf0d0f99df0e44ba57 from master

comment:7 Changed 2 months ago by Carlton Gibson

Triage Stage: AcceptedReady for checkin

Bar a last review of edits and a squash, this looks ready to go.

comment:8 Changed 2 months ago by Mariusz Felisiak <felisiak.mariusz@…>

Resolution: fixed
Status: assignedclosed

In 4a954cf:

Fixed #30573 -- Rephrased documentation to avoid words that minimise 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.

Note: See TracTickets for help on using tickets.
Back to Top