Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Copy editing guideline for this issue
The User Guide has an index, which you can currently see at:
https://userguide_new-drupal.dev.devdrupal.org/d8guide/en/_index.html
(user name/password: drupal/drupal)
The entries in the index are in each individual topic file, and they look like this:
(((Contributed module,downloading)))
That example would make a main entry with text "Contributed module", and under that a sub-entry for "downloading". And next to the sub-entry, you'd see a link to the topic that has this index entry in it.
Since the index entries were added to each topic by the individual topic authors, they didn't all come out consistent with each other.
So... for this task, we need to make them more consistent. Guidelines:
- Singular vs. plural: Let's always use singular. So it should be "Block, definition", not "Blocks, definition".
- There shouldn't be any quote marks.
- Watch for synonyms and duplication. For instance, there are entries for "Contributed module, finding" and "Contributed module, searching". We probably could drop the "searching" entry, as it doesn't really add anything.
You'll need to read through the index, finding entries to fix, and then fix them in the individual topic files where they are defined.
Task Instructions
- To claim this task, assign this issue to yourself (see instructions below). Only claim a task if you can complete it in about two weeks.
- See the instructions below to "clone" the guide, edit the entire user guide so that it follows the above copy editing guideline, and make a patch file. Do not make other edits at this time -- other edits will be taken care of in other issues. If you find that you cannot complete the whole task, but have made some progress, make a patch file for the part you've done.
- Upload the patch file to this issue, in the Files section.
- Set the Issue Status to Needs Review, in the Issue Metadata section.
- Write a comment stating what you've done.
- In this comment, add "Attribution" information
https://www.drupal.org/u/msmith[Mary Smith] or https://www.drupal.org/u/jsmith[Joe Smith] of https://example.com[Example Company] - Someone will review your work, and either accept it, or set it back to Needs Work for more attention.
- If the status is set to Needs Work, make the requested changes, make a new patch file, and upload it. Iterate until it is fixed.
Detailed Instructions for Assigning Issues and Patching
Assigning an issue to yourself
- Scroll to the bottom of the issue to Add new comment.
- Open the "Issue metadata" section if it is collapsed.
- Put your user name in the "Assigned" field, add a short comment stating that you are claiming the task, and Save.
Editing and making a patch file
- In order to make a patch file, you will need to use the Git version control software. There are generic instructions on Git at: https://www.drupal.org/documentation/git/ -- if you have never used Git, you will probably want to read the introductory material, and you'll need to install Git.
- Specific Git instructions for the User Guide project can be found at https://www.drupal.org/project/user_guide/git-instructions . Follow the instructions to "clone" the repository (see the "One-time only" instructions).
- Make the edits for this issue, using a plain-text editor. The source files are located in the source/en subdirectory, and have extension .txt, and are in AsciiDoc format (see below).
- Go back to the specific Git instructions page and follow the instructions there to make a patch file. There are also more detailed git patch instructions in the Git documentation section linked above.
AsciiDoc formatting
The documentation in this project is formatted using AsciiDoc. The Formatting page in the User Guide guidelines (login: drupal / drupal ) has links and details for how to format text properly, make cross-links between topics, etc.
| Comment | File | Size | Author |
|---|---|---|---|
| #25 | 2699833-copyeditingindexstylephase2.patch | 17.39 KB | avanraaphorst |
| #19 | 2699833-copyeditindexstylephase1.patch | 4.61 KB | avanraaphorst |
| #13 | 2699833-copyeditindexstyle.patch | 26.21 KB | avanraaphorst |
| #10 | block-concept.txt | 1.05 KB | avanraaphorst |
Comments
Comment #2
jhodgdonNote: I spoke to avanraaphorst today on the phone. She is an expert indexer, and will be working on this aspect of the index, as well as the more technical concern of what should be actually indexed. So I've currently assigned this to myself until she changes the assignment to herself.
She plans to submit an initial patch that updates the indexing for a small number of topics, as a start, and then continue one once Joe/myself have taken a look. THANKS Anna!
Comment #3
avanraaphorst commentedI'm claiming this task
Comment #4
jhodgdonavanrapaphorst: Can you use the Assigned field in "Issue metadata" to assign it to yourself? Thanks!
Comment #5
avanraaphorst commentedI'm claiming this task
Comment #6
jhodgdonI've now centralized instructions for the editing tasks. I'll go ahead and leave the instructions on these issues, but you can also go to
https://userguide_new-drupal.dev.devdrupal.org/guidelines/instructions.h...
(log in with drupal / drupal)
and follow the instructions there (probably more complete).
Comment #7
avanraaphorst commentedThis is a test to see if I'm doing the task correctly. I'll be doing circling back to correct other singular/plural problems.
Comment #8
ifrikHi avanraaphorst,
did you forget to upload any files or patches for reviewing?
Comment #9
jhodgdonComment #10
avanraaphorst commentedTrying again making it through the workflow on the first file I have changed. I updated the (single) index entry.
Comment #12
jhodgdonThanks Anna!
When I downloaded the new block-concept.txt file and put it into my local Git repo, it showed that every line of the file had changed -- it apparently has DOS line endings instead of Unix line endings. So... something is going on in your text editor. Maybe you're using Notepad on Windows? It is kind of evil that way.
Anyway, I was able to use the dos2unix command line utility on my Linux box and convert the file. At that point, the one line that you changed looked good. So I went ahead and committed that change to the User Guide. ... without attribution though -- at some point please provide your preferred attribution line (see instructions in the issue summary).
Also, going forward, if you are editing a bunch of the topic files, it will be much easier for committers to deal with if you can make a patch file instead of uploading each individual topic file.
Thanks! I'll set this back to Active until you make another patch or edit.
Comment #13
avanraaphorst commentedhttps://www.drupal.org/u/avanraaphorst[Anna van Raaphorst]
Oops, I AM using Notepad -- I'll look for something better when I work on the next issue.
The work on this issue should now be complete, but there will be further index changes when I do the complete index review, updates, and additions. I believe there are approximately 100 files, and I changed 65 of them. For the next issue I expect to be touching almost every file at least once.
General questions/comments:
- It seems as though the term in the glossary should be the "official" one to be used in both the topic title and index entry -- yes? For example, always "User one" instead of sometimes "User 1."
- We aren't always consistent with gerunds and nouns -- for example sometimes "translation" and sometimes "translating." I'll try to fix that in the next round.
- The singular vs. plural issue is also not what it should be yet. I don't know... should the index entry be plural if the word is plural in the title? The question of "permissions" I think is clear -- use plural -- but with other terms it's not so clear-cut.
- I didn't do this, but I feel strongly that an acronym index entry should include both the acronym AND what it stands for. Otherwise, users will sometimes click on the link and find that they are not interested in that term at all. Better to stop them from making the click. Examples would be UI, CMS, WYSIWYG. I was tempted to put the meaning in parentheses after the acronym, but I don't know how to handle special characters yet... So I left it for next time.
- There are some issues with the fact that it's a two-level index (as it should be, I think). For example, there might be a term "Server" and ALSO a term something like "Server information." That's not too bad if there are only a handful of two-word terms, but in a couple of cases there were as many as 6 or so. I'll work on that in the next round.
- There is a little confusion when the index entry doesn't match the title -- for example, "Updates, following" index entry but the title is "keeping track of updates." It would be best to have consistency (and I'd vote for "keeping track of" on that particular one).
Comment #14
jhodgdonThanks for all of your work on this!
Regarding your questions...
a) Yes probably the terms in the glossary would be the best source for spelling choices like "User one".
b) Gerunds vs. -tion -- let's use gerunds. I'll add that to the standards document.
c) Singular vs. plural - maybe we should change the standard to use plural? I think being consistent would be good. What do you think is more standard for indexes in general? I would be happy to defer to your judgement.
d) Agreed on acronyms -- we should include both the acronym and what it stands for in the index.
e) Agreed on making the index entries more consistent with the topic titles.
So... I also looked at the patch and I think it needs some work and/or discussion in a few places:
This looks a bit odd to me. Theme and Block are now singular, but regions is still plural. Maybe we should either make them both singular or both plural?
Hm. So I had at some point made a standard that the primary entry shoudl be a noun and not a verb. But I think you are right that if possible, we should use gerunds throughout instead of -tion, so I'll update the standards page.
I think we should drop this entry. We are not going to have entries everywhere (I think) for "Configuring, xyz". Basically half of the User Guide is about configuring things. Right? So I don't think we should do it here.
I don't think this should be in "Title Case". Probably just capitalize "User" and not "account setting"?
It seems like for primary entries being verbs, they are usually pretty generic verbs... Editing I think falls into this category. Maybe change this to
Editor, in-place
This entry does not make sense to me for this topic.
If I saw this entry, I would think that it meant the topic was about how to extend a theme. But it isn't, it's about how to install a theme.
I'm torn about including the word "enable" in the index when referring to modules or themes.
The reason is that it is an outdated term from previous versions of Drupal -- for instance, in Drupal 7, you could "install" a module and then "enable" it, and you could "disable" a module without "uninstalling" it. That functionality was removed in Drupal 8, so there is only "installing" and "uninstalling"...
I guess though that for the index, we should go ahead and index under "enabling" even though in the text itself, we will be removing that term so as to be precise and conform to what the Drupal UI now does.
Thoughts?
Not sure if we want the first word to be changed into a verb here?
We have Requirements, server and Server, requirements.
But we don't have Requirements, PHP or Requirements, MySQL, etc.
Do we need these?
And should "PHP requirements" be something like "PHP, required version"?
So... This is a bit odd.
To install Drupal, you need either Apach, or Nginx, or Hiawatha, or IIS.
Nginx is not a requirement per se.
Similar for MySQL vs. PostgreSQL vs. SQLight.... and incidentally it should be SQLite not SQLight!
But anywa, maybe all of these should be something more like:
Apache, compatible versions
???
I am not sure about this one.
The topic does mention an "installation profile" (Standard or Minimal).
It isn't really about installing a profile.
This is inconsistent with the others you have changed to Translating.
This change is out of scope for the issue.
same here.
I suspect that these changed lines in several places in the patch are line ending problems? I cannot see any change visually between the two lines.
I'm not sure we want to lose the entry under Term. Maybe change this to:
Term, taxonomy
Comment #15
avanraaphorst commentedBelow are responses to Jennifer's comments. No file changes yet.
Comments a) and b): Agreed
Comment c): The singular seems to make more sense for terms defined in the glossary (e.g. Block). However, the plural seems to make more sense elsewhere, especially when the term appears in the plural form in the topic title. How about if I just try that and see how it goes?
Comments d) and e): Agreed
1) See c) above.
2) I think the gerunds will work almost everywhere.
3) Agreed. I will drop the entry.
4) Agreed.
5) I'll make your suggested change.
6) I'll change the verb to installing.
7) I hate to put in a link to information that isn't there without some explanation. Experienced users might figure it out, but a new user would probably be confused. How about using a "see" index entry?
8) I'll wordsmith this one. I probably should check to see if there are other, similar problems.
9) I'll use your suggestion and will give it more thought in "round 2."
10) I think this will also take a little thought.
11) I'll fix this.
12) I'll eliminate "configuring." "Content translating" sounds funny to me. So far I like "content translation" best.
13) - 15) I don't know what happened here. I'm working on getting all of my messed-up files (line-end characters) fixed.
16) Agreed.
Comment #16
jhodgdonResponse to comment #15...
c) Your strategy for singular/plural makes sense to me. The main thing is not to have both "block" and "blocks" in the index, anyway.
7) I do not think that AsciiDoc has a way to make a "see" entry in the index. At least, if there is, it is not in the AsciiDoc User Guide. So. In that case, I agree we should go ahead and put "enabling" in the index. We should still, I think, not mention it in the text (which I think will be clear enough without the word "enable").
8) How about "Install, preparing for"? Just a thought.
12) Agreed that "Content translation, configuring" seems much much much better than "Content translating, configuring".
13-15) Don't worry too much about the end-of-line characters for this pass. What I can do when I apply the patch is afterwards run dos2unix on my command line, and fix them back. ;)
Glad we're in agreement here! This is looking like even the first pass will be a huge improvement!
Comment #17
avanraaphorst commentedQuestions for Jennifer (no change to status):
1. Have you committed to the repository the files I sent you in the patch?
2. If yes, why don't the published files visible in Drupal.org reflect the changes I made to the index entries? (Maybe you don't update the published files very often..?)
3. The key question is on which copies of the files should I make further changes? My local changed files or a new set that are the result of a git pull, or..? (It appears that many of the files I changed have had further changes.)
Thanks, Anna
Comment #18
jhodgdonThe only change I committed from here was the initial one in the block-concept file.
The files on the devdrupal.org pages are updated after each commit, so they should normally be up there within an hour.
The other changes have come from other issues... if they are causing you problems, I am sorry!
So. You should be able to revert your local changes, then do a git pull, and then use either the "patch" command or "git apply" to apply the patch you uploaded before again. Let me see... Yes, the patch still applies for me with no errors. Does that work for you? Otherwise, let me know and I can apply and commit it as a first pass, and you can start from there.
Commands:
Comment #19
avanraaphorst commentedQuestions for Jennifer:
Because I've changed to the Notepad++ editor and we've agreed to some indexing conventions that I wasn't following when I did the first changes I decided to start over from the beginning.
Just now I edited four files: the glossary and others that (mis)used special characters. Now I'd like to see if I can get through the workflow end to end and get these changes reflected in the repository.
I've created a new patch file (see the one ending in "-phase1") and attached it here.
My expectation is that you will use the attached patch to commit the work I just did to the repository. If that correct? I'm still confused about how the commit takes place: am I supposed to do that myself? If so, I can't find any instructions explaining how to do it.
Sorry if I'm missing something that is right under my nose...
If this works then I'll continue with additional changes we discussed for this issue.
Thanks, Anna
Comment #20
jhodgdonYes, that's right: you make a patch, and either Joe (eojthebrave) or I commits the patch to the repository. That is the workflow for all Drupal.org projects -- there is a small set of "committers" for each project, who have rights to commit the changes, but at least most projects welcome help from all members of the community, who can submit patches for review/commit. Thanks for asking for clarification!
And sorry this has apparently been frustrating -- I think you've got the workflow down now -- thanks for persevering!!
So, regarding the patch -- looks great!
One question:
On this one, do you think we should try to leave it as:
(((Term (taxonomy), overview)))
rather than just removing it? That seems to work... and I thought maybe having the word "Term" in the index, in the context of taxonomy, might be useful... maybe not, but you can take it out in the next pass if not. ;)
Anyway, I made that one change to your patch, and committed it. I will add attribution to the attributions page in a separate commit... that page has some other problems I noticed. oops.
That much is now done. Thanks! Setting back to Active for additional work (singular/plural stuff and duplication).
Also... Can you take a look at the guidelines that are now in place, in our Contributor Handbook, for indexing, and let me know if we should make changes there? Thanks!
Comment #22
jhodgdonOh sorry. The index guidelines I requested that you look at are at the bottom of this page:
https://userguide_new-drupal.dev.devdrupal.org/guidelines/guidelines-wri...
I've tried to update them based on our discussions so far... I'm interested to see what you think. Thanks!
Comment #23
avanraaphorst commentedNo code changes; discussion only:
Hi, Jennifer --
Thanks for the clarifications and new information. I'm not actually so surprised that this first round is taking awhile, because I'm not familiar with either the doc or the tools. In any case, I hope to finish up on the copy edit over the weekend. I'd be happy to look at your style guide, also -- will you create an issue for that, or should I just send you an email with my comments?
-Anna
Comment #24
jhodgdonSounds good!
You can just add a comment here or on the other indexing issue, if you have suggestions for the guidelines. Thanks!
Comment #25
avanraaphorst commentedHi, Jennifer --
This is still not perfect stylistically, but I'd like to move on to the new issue if it's okay with you. One of the problem areas is still singular vs. plural. If you look at the index entries for theme and view you can see what I mean. I generally made the definitions and overviews singular, but there are other entries where plural makes more sense. Also, the titles are not consistent. I don't know if you want to try to straighten all that out -- maybe not worth it at this stage -- but it would be tidier.
I'll give you some comments on your style guide after I finish the new issue.
Thanks, Anna
Comment #26
avanraaphorst commentedComment #28
jhodgdonSure, move on to the new issue whenever you want to!
Meanwhile, I applied the patch here, with three minor changes (the rest looked perfect to me):
The topic title should be in Title Case actually.
Here I think "editorial workflow" should not be capitalized at all. Anyway I just didn't include the changes to planning-workflow at all.
Probably should be "Text format" right? I didn't see this index entry anywhere else in the guide so I went ahead and changed this one. Seemed like none of the other index entries had both words capitalized.
So, marking this Fixed and we can move on to the other issue now. THANKS very much for all your work on this!