Problem/Motivation

I just got an issue report about the usage of "i.e." and "e.g." in my module's documentation (#2747837: Replacing i.e. and e.g. with English words). The issue creator argues that these are commonly misunderstood/confused and therefore make the documentation less clear.

I wanted to a) ask everyone's opinion on this, whether this really adds confusion and should be avoided, and, if yes, to b) propose adding this to our documentation standards (and also removing our usage of those acrabbreviations in the coding standards themselves).

Also, for reference:

/var/www/drupal8$ git grep  'e\. \?g\.\|i\. \?e\.' | wc -l
883

Benefits

If we adopted this change, the Drupal Project would benefit by ...

Three supporters required

  1. https://www.drupal.org/u/{userid} (yyyy-mm-dd they added support)
  2. https://www.drupal.org/u/{userid} (yyyy-mm-dd they added support)
  3. https://www.drupal.org/u/{userid} (yyyy-mm-dd they added support)

Proposed changes

Create an MR with all proposed changes.

2. Repeat the above for each page or sub-page that needs to be changed.

Remaining tasks

  1. Create this issue in the Coding Standards queue, using the defined template
  2. Add supporters
  3. Create a Change Record
  4. Review by the Coding Standards Committee
  5. Coding Standards Committee takes action as required
  6. Discussed at a Core Committee meeting, if it impacts Drupal Core
  7. Final review by Coding Standards Committee
  8. Documentation updates
    1. Commit the MR
    2. Publish change record
    3. Remove 'Needs documentation edits' tag
  9. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a full explanation of these steps see the Coding Standards project page

Comments

drunken monkey created an issue. See original summary.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

We have/had an effort to remove these from the Core docs (it may not be finished yet).

This was started by me, because I observed that a lot of the time, people used i.e. and e.g. incorrectly (substituting one for the other), which indicated that at least some people who attempted to write documentation didn't really understand the difference between them or what they really meant.

In addition, they are Latin abbreviations, and not English.

And furthermore, the correct punctuation for them is hardly ever used and looks really odd (even though it is correct). It should be, for instance:

Content types; e.g., Basic page and Article, are useful ways to...
Content types; i.e., the bundles of the Node entity, are useful ways...

For these reasons, it seemed like it would lead to clearer documentation if we used English words instead of either i.e. or e.g.

But I don't think it's a "coding standard" necessarily, per se... more of a "writing style" guideline.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

As a note, we have a "content style guide" that all documentation is supposed to follow:
https://www.drupal.org/drupalorg/style-guide/content

The style guide seems to be a bit orphaned at the moment... but node/1354 does say to follow it:
https://www.drupal.org/node/1354#drupal

drunken monkey’s picture

drunken monkey
he/him
Primary language German
Location Vienna, Austria
commented

Content types; e.g., Basic page and Article, are useful ways to...
Content types; i.e., the bundles of the Node entity, are useful ways...

What style is that from? I always followed the Chicago Manual of Style, there, and that mostly recommends commas, as far as I'm aware [1][2]. Though always putting them both before and after the abbreviation still looks a bit odd, it's at least not as odd as semicolons.

As a note, we have a "content style guide" that all documentation is supposed to follow:https://www.drupal.org/drupalorg/style-guide/content

Good to know, but that guide doesn't really discuss "e.g." or "i.e." at all – it does use the former, though, quite a lot. Which would again point to its use being OK.

Also, your arguments seem to just deal with people misusing them – but if I know how to use them, and don't commit any patches misusing them, that wouldn't be a problem. Would you say they hinder understanding when reading, too?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Yes, I would say, based on my experience of people misusing them when writing documentation, that many people do not understand them properly when reading them either.

quietone’s picture

quietone commented
Issue summary: View changes

Convert to new template.

nexusnovaz’s picture

nexusnovaz commented

I think for the sake of making things clearer to non-native English speakers, we should use "for example" / "that is" in place of "e.g." / "i.e."

quietone’s picture

quietone commented
Status: Active » Closed (won't fix)

This was discussed in two Coding Standard meetings; #3554913: Coding Standards Meeting Tuesday 2025-11-25 2100 UTC and #3573908: Coding Standards Meeting Tuesday 2026-01-28 2000 UTC.

In both cases there was more support for not changing this than there was for it. Key points were that the Drupal Content style guide itself uses them and that, in context, the meaning was clear. In other word, there use wasn't preventing understanding of the text, whether there were used correctly or not. And that included feedback from a non native English speaker. Therefor, I am closing this issue.

If, at a later time, there is support for this, open a new issue and reference this one. Thanks.

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.