Copy editing guideline for this issue

  • When providing instructions to click on a link or button, use the phrase “Click (link text)” - not “click on” or “select” or other terms.
  • For a drop-down list or radio button, say “Select (choice)”.
  • For a checkbox, say “Check (choice)”.
  • Instead of using using Choose, say Select, Click of Check.

Make sure that the actual UI text you are selecting or clicking on is in italics.

Task Instructions

  1. 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.
  2. 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.
  3. Upload the patch file to this issue, in the Files section.
  4. Set the Issue Status to Needs Review, in the Issue Metadata section.
  5. Write a comment stating what you've done.
  6. 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]
  7. Someone will review your work, and either accept it, or set it back to Needs Work for more attention.
  8. 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

  1. Scroll to the bottom of the issue to Add new comment.
  2. Open the "Issue metadata" section if it is collapsed.
  3. 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

  1. 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.
  2. 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).
  3. 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).
  4. 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.

CommentFileSizeAuthor
#20 interdiff-2698977-18-20.txt9.75 KBifrik
#20 2698977-20.patch48.38 KBifrik
#18 interdiff-2698977-12-18.txt12.75 KBifrik
#18 2698977-18.patch47.96 KBifrik
#12 interdiff-2698977-8-12.txt26.79 KBifrik
#12 2698977-12.patch47.67 KBifrik
#9 2698977-8.patch33.57 KBbatigolix

Comments

ifrik created an issue. See original summary.

ifrik’s picture

ifrik
she/her
commented
Parent issue: #2687905: Copy edit: Avoid please and similar words »
batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Assigned: Unassigned » batigolix

mine!

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Title: Copy edit: Click and Select » Copy edit: Click, Select and Check
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Doh! :)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I'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).

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Issue summary: View changes
batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

Jennifer: I am also looking for occurences of "Choose". Should I add that to the guidelines?

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Assigned: batigolix » Unassigned
Status: Active » Needs review
StatusFileSize
new 2698977-8.patch33.57 KB

Find attached a patch

Attribution info
https://www.drupal.org/u/batigolix[Boris Doesborg]

ifrik’s picture

ifrik
she/her
commented
Status: Needs review » Needs work

Thanks batigolix,

there are no instance of "choose" used in relation to links, radio buttons, drop-down menu and check boxes.

But there are quite a few instances of click, select and check that are followed by the link text in double quotes or reference to "button".

ifrik’s picture

ifrik
she/her
commented
Assigned: Unassigned » ifrik

I'll continue on this one.

ifrik’s picture

ifrik
she/her
commented
Status: Needs work » Needs review
Issue tags: +DrupalBCDays
StatusFileSize
new 2698977-12.patch47.67 KB
new interdiff-2698977-8-12.txt26.79 KB

I've checked for instanced of click, select and change and edited them where appropriate.

There are some left where general editing should take care of them, for example when in phrases like "click the pencil icon" etc.

Where the terms are used they are followed by the link label or option in italics instead of in quotation marks or so.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Needs work

Whew, that's a big patch, thanks!! I reviewed it carefully and have a few suggestions.

Most of them are about drop-down lists of operations buttons. These are actually links organized into button drop-downs, so I think we should say "click" for them.

Also, many of these buttons/links are duplicated throughout the page (such as the operations on each content item row in the admin/content page or the user accounts on admin/people). I saw one really good example in this patch of how to describe this:

Click _Edit_ in the row of the user account you want to update.

Let's standardize on that sort of style for when we have to say this.

  1. +++ b/source/en/block-create-custom.txt
@@ -22,7 +22,7 @@ permission. See <<user-permissions>>
-. Click _+Add custom block_. The _Add custom block_ page appears.
+. Click _Add custom block_. The _Add custom block_ page appears.

    The link text actually does have a + sign in it. 

  2. +++ b/source/en/block-create-custom.txt
@@ -52,7 +52,7 @@ appear.
-// Go to block/add, enter field values & click Save
+// Go to block/add, enter field values & click _Save_

    This is in a comment, so we don't need _Save_ to be in italics. 

  3. +++ b/source/en/config-theme.txt
@@ -61,7 +61,7 @@ supplied by the theme."
-. Under "Upload logo image" select "Choose file" and locate the logo file you
+. Under "Upload logo image" click _Choose file_ and locate the logo file you
 want to upload to your site. Note: you can also set a universal logo for all

    I don't know about this one. The "choose file" button is provided by the browser, not by Drupal, and for instance Firefox says "Browse" on it, not "Choose file".

    So, I think we should change this whole section to say something like:

    Under _Upload logo image_, upload the logo file.

  4. +++ b/source/en/config-uninstall.txt
@@ -31,7 +31,7 @@ running. If not installed yet, we recommend you to refer the guide at
 . Enable the checkbox corresponding to one or more modules you wish to disable

    "Enable the checkbox" should be updated for this issue. 

  5. +++ b/source/en/config-user.txt
@@ -25,7 +25,7 @@ _Account settings_ (admin/config/people/accounts): we find quick settings on
+. In Registration and cancellation, (in this example) check _Administrators
 only_ as for who can register user accounts. Leaving the self-registered

    This is a radio button. It should say "select". 

  6. +++ b/source/en/content-in-place-edit.txt
@@ -51,7 +51,7 @@ a hovering dialog box will appear.
+. Click the field you want to edit, such as the Title or Body field. If the

    Maybe

    Click the name of the field...

    ? 

  7. +++ b/source/en/extend-module-install.txt
@@ -40,7 +40,7 @@ below do not work to download and unpack the module files, follow the steps in
-. Right click the _tar.gz_ download link and copy the address.
+. Right click _tar.gz_ to copy the address.

    Just right clicking is not enough to copy the address. You have to right click and then select Copy link address.

    This is also browser-dependent, and what do you do on Mobile? No way to right-click on a phone.

    So... we may need to change these instructions. 

  8. +++ b/source/en/language-add.txt
@@ -22,10 +22,9 @@ The multilingual modules must be enabled. See <<language-enable>>.
-. Select _+ Add language_
+. Click _Add language_.

    The + sign is part of the button text I think? 

  9. +++ b/source/en/language-config-translate.txt
@@ -23,12 +23,12 @@ Translate the labels on the _Recipes_ view page into Spanish.
+. Locate the _Recipes_ view and select _Translate_ from the drop-down list.

    Hm. This is actually clicking on a link in a drop-down button, so I think we should say "click" not "select"? 

  10. +++ b/source/en/language-config-translate.txt
@@ -23,12 +23,12 @@ Translate the labels on the _Recipes_ view page into Spanish.
+. Click _Displays_ > _Master display settings_ > _Recipes default display
 options_ > _Exposed form_ > _Reset options_.

    Hm. This is kind of a navigation instruction within the page.

    Maybe something like:

    Find the _Displays_ > _Master.... > _Exposed form_ > _Reset options_ section. 

  11. +++ b/source/en/menu-reorder.txt
@@ -22,8 +22,7 @@ At least two menu items must be linked from the content. See
+currently on your site. Find the menu you wish to edit and click _Edit Menu_. You could also reach this page using the

    rewrap to 80... also there are lots of "edit menu" buttons on the screen and we lost the information that we want to click just that specific one. Is that the right text for the button anyway? 

  12. +++ b/source/en/structure-adding-reference.txt
@@ -31,8 +31,8 @@ The content types _Recipe_ and _Vendor_ are defined. See
+types_ (admin/structure/types). Then select _Manage fields_ in the drop-down

    Again this is a drop-down list of links, not a select list, so I think we should use the word "click". 

  13. +++ b/source/en/structure-content-type-delete.txt
@@ -22,20 +22,19 @@ website.
-. You can see list of all the available types of content having a dropdown
+. You can see list of all the available types of content having a drop-down

    This change is out of scope, and also incorrect. We have a separate issue. 

  14. +++ b/source/en/structure-form-editing.txt
@@ -28,10 +28,10 @@ with an _Ingredients_ taxonomy term reference field (see
+types_ (admin/structure/types). Then select _Manage form display_ drop down

    click not select 

  15. +++ b/source/en/structure-taxonomy.txt
@@ -48,7 +48,8 @@ content items that are classified with that term. For example, if you created
-//Login to your Drupal 8 site as an administrator and click on a _carrots_ ingredient of _Fresh Carrots_ recipe page.
+//Login to your Drupal 8 site as an administrator and click on a _carrots_
+ingredient of _Fresh Carrots_ recipe page.

    This is a comment.

    Either leave it as one long line, or add a // to the beginning of the second line. The change here will make some of the text of the comment visible. 

  16. +++ b/source/en/structure-view-modes.txt
@@ -25,7 +25,7 @@ mode_. Examples of view modes are:
+(admin/structure/types) and select _Manage display_ from the dropdown button. In

    click not select 

  17. +++ b/source/en/user-new-role.txt
@@ -31,7 +31,7 @@ allowing the creation of a new custom role.
-. Click on the _+Add Role_ button above the list of roles.
+. Click _Add Role_ above the list of roles.

    There is a + in the button label I think? don't remove that... 

  18. +++ b/source/en/user-permissions.txt
@@ -32,7 +32,7 @@ The site needs to have a _Vendor_ role. See <<user-roles>>.
+. Select _Edit permissions_ in the drop-down list for the _Vendor_

    select -> click 

  19. +++ b/source/en/user-roles.txt
@@ -32,20 +32,19 @@ already exist.
+.  On the _Edit_ page, scroll down to _Roles_ section. Check or uncheck the desired roles for the user account.

    Line too long. 

  20. +++ b/source/en/views-block.txt
@@ -27,63 +27,63 @@ only.
+(admin/structure/views). Find the view "Recipes" and select _Edit_ from its

    click not select 

  21. +++ b/source/en/views-block.txt
@@ -27,63 +27,63 @@ only.
+. Click the _Display name: Block_, this opens _The name and the description of

    no "the" after "Click" at the start of this line 

  22. +++ b/source/en/views-create.txt
@@ -59,7 +59,7 @@ image:images/views-create-wizard.png["Add new view wizard",width="100%"]
+. Select _Add_ from the dropdown button in the _Fields_ section. The _Add

    Select -> Click 

  23. +++ b/source/en/views-create.txt
@@ -81,7 +81,7 @@ appears.
+. Select _Add_ from the dropdown button in the _Fields_ section. The _Add

    Select -> Click 

  24. +++ b/source/en/views-create.txt
@@ -111,7 +111,7 @@ wizard.
+. Select _Rearrange_ from the dropdown button in the _Fields_ section. The

    Select -> Click 

  25. +++ b/source/en/views-duplicate.txt
@@ -29,14 +29,14 @@ an option to filter on ingredients.
+(admin/structure/views). Find the view "Vendors" and select _Duplicate_ from its

    select => click 

  26. +++ b/source/en/views-duplicate.txt
@@ -51,7 +51,7 @@ image:images/views-duplicate_title.png["Change view title",width="100%"]
+. In the _Fields_ section click _Content: Body_ then select _Remove_ in the

    select -> click

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Also found this when grepping on another issue:

source/en/language-content-config.txt:. In the Custom language settings enable _Content_, _Custom block_ and _Custom

these are checkboxes.

ifrik’s picture

ifrik
she/her
commented

Thanks for reviewing this. I'm all in favour for consistency so I'm happy to work on this further.

About the "+ Add something": As far as I'm aware the "+" is added by the theme layer. I'll check that but if it's not part of the actual UI text, then I would rather leave it out.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Ah, yes you are correct! That is actually in the theme layer and not in the UI text. I had no idea. So yes, let's take those + signs out.

ifrik’s picture

ifrik
she/her
commented

Rerolling.

ifrik’s picture

ifrik
she/her
commented
StatusFileSize
new 2698977-18.patch47.96 KB
new interdiff-2698977-12-18.txt12.75 KB

Thanks, I rerolled the patch and then edited it according to comment 13-18.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Phew! Big patch. Thanks!

Getting better... I think we still need to fix some things though:

  1. +++ b/source/en/config-uninstall.txt
@@ -48,9 +48,11 @@ dependent module(s) and functionality.
-//Login to your Drupal 8 site as an administrator; then in the _Manage_ administrative menu, navigate to _Extend_ > _Uninstall_ tab, select _search_ module, and click the _Uninstall_ button.
+//Login to your Drupal 8 site as an administrator; then in the _Manage_
+administrative menu, navigate to _Extend_ > _Uninstall_ tab, select _search_
+module, and click _Uninstall_.

    This was a comment line. To break it up to 80 character lines, you need to add // at the start of the added lines. Otherwise the text will appear in the output. 

  2. +++ b/source/en/language-add.txt
@@ -22,10 +22,9 @@ The multilingual modules must be installed. See <<language-enable>>.
+. Select _Add language_

    Select -> Click (this is a button/link). 

  3. +++ b/source/en/language-add.txt
@@ -22,10 +22,9 @@ The multilingual modules must be installed. See <<language-enable>>.
-. Choose the language you want to add from the drop down list and click _Add
-language_. The language is added.
+. Select your prefered language and click _Add language_.

    Nicely compacted! :) 

  4. +++ b/source/en/language-config-translate.txt
@@ -23,13 +23,13 @@ Translate the labels on the _Recipes_ view page into Spanish.
-. Locate the _Recipes_ view and choose _Translate_ from the drop-down button.
+. Locate the _Recipes_ view and click _Translate_ from the drop-down list.

    We actually want to call this a "dropdown button" here (which is the subject of another issue: #2703223: Copy edit: Dropdown (button)). But "click" is correct. 

  5. +++ b/source/en/language-config-translate.txt
@@ -23,13 +23,13 @@ Translate the labels on the _Recipes_ view page into Spanish.
-. Select _Displays_ > _Master display settings_ > _Recipes default display
-options_ > _Exposed form_ > _Reset options_.
+. Find _Displays_ > _Master display settings_ > _Recipes default display
+options_ > _Exposed form_ and click _Reset options_.

    This is a good way to express what needs to be done! 

  6. +++ b/source/en/menu-reorder.txt
@@ -21,10 +21,8 @@ At least two menu items must be linked from the content. See
+you want to change by clicking on its _Edit Menu_. You can also reach this page using the <<config-overview,contextual links>> for the menu.

    clicking on -> clicking

    Hm... I think if we're saying "its" (which I think we need), we need to say button or link, something like:

    ... by clicking _Edit menu_ from its _Operations_ dropdown button...

    ???

    Also this needs to be rewrapped to 80 character lines. 

  7. +++ b/source/en/structure-taxonomy-setup.txt
@@ -61,15 +61,14 @@ image:images/structure-taxonomy-setup-5.png["Ingredients List page",width="100%"
+. Select _Add field_. First you will select your data type, in this case a

    I think Add field is a button? Should be Click. 

  8. +++ b/source/en/structure-taxonomy.txt
@@ -48,7 +48,8 @@ content items that are classified with that term. For example, if you created
-//Login to your Drupal 8 site as an administrator and click on a _carrots_ ingredient of _Fresh Carrots_ recipe page.
+//Login to your Drupal 8 site as an administrator and click _carrots_
+ingredient of _Fresh Carrots_ recipe page.

    Do not change this comment, or if you do and decide to rewrap, the second line still needs to start with // 

  9. +++ b/source/en/structure-view-modes.txt
@@ -25,7 +25,7 @@ mode_. Examples of view modes are:
+(admin/structure/types) and select _Manage display_ from the drop-down list. In

    This is a link in a drop-down list, so we want to "click" it. 

  10. +++ b/source/en/views-block.txt
@@ -27,36 +27,36 @@ only.
-. In the Title section, click on _Title: Recipes_. Change _For This block
+. In the Title section, click _Title: Recipes_. Change _For This block
 (override)_ the Title to "New Recipes" and click _Apply (this display)_.

    This may still be misleading.

    They need to change where it says "All displays" in a Select list, to saying "For this block only".

    So this is a Select operation? 

  11. +++ b/source/en/views-block.txt
@@ -27,36 +27,36 @@ only.
-. In the Format section, click on _Format: Grid_ then in the appearing pop-up
-choose _For This block (override)_ the Style checked for "Unformatted
+. In the Format section, click _Format: Grid_. Then in the appearing pop-up
+select _For This block (override)_ the Style checked for "Unformatted
 list". _Apply (this display)_. You can further configure the _Style options_ in
 the pop-up that now appears.

    This still seems a bit garbled. 

  12. +++ b/source/en/views-block.txt
@@ -68,22 +68,22 @@ display)_.
+appearing pop-op choose _For This Block (override)_ and click _Remove_ at

    choose -> select 

  13. +++ b/source/en/views-create.txt
@@ -81,7 +81,7 @@ appears.
+. Select _Add_ from the drop-down list in the _Fields_ section. The _Add

    Select -> Click 

  14. +++ b/source/en/views-duplicate.txt
@@ -51,7 +51,7 @@ image:images/views-duplicate_title.png["Change view title",width="100%"]
+. In the _Fields_ section select _Content: Body_ then choose _Remove_ in the

    I think this is a link to click on, not an option to select? 

  15. +++ b/source/en/views-duplicate.txt
@@ -80,7 +80,7 @@ new path "recipes" in the pop-up then _Apply_. Then via the _Menu_ pop-up change
+to "Yes": click _No_ and choose for using AJAX in the pop-up then _Apply_.

    choose -> select

ifrik’s picture

ifrik
she/her
commented
Status: Needs work » Needs review
StatusFileSize
new 2698977-20.patch48.38 KB
new interdiff-2698977-18-20.txt9.75 KB

Thanks.
I hadn't quite seen the issue about "dropdown buttons".
For 14: that's a select list and a link to click.

Some of the more complex pages like the Views ones probably need more general editing anyway.

  • jhodgdon committed 270e06a on 8.x-0.x 
    Issue #2698977 by ifrik, batigolix, jhodgdon: Copy edit: Click, Select...
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Fixed

This looks great!

I had a couple of notes:

  1. I've been making other commits today so the patch didn't quite apply, but I was able to take care of that myself.
  2. +++ b/source/en/menu-reorder.txt
@@ -21,10 +21,9 @@ At least two menu items must be linked from the content. See
+button. You can also reach this page using the <<config-overview,contextual links>> for the menu.

    line goes over 80 characters, needs rewrapping. I fixed this before I committed the patch. 

  3. +++ b/source/en/structure-view-modes.txt
@@ -25,7 +25,7 @@ mode_. Examples of view modes are:
+(admin/structure/types) and clikc _Manage display_ from the dropdown button. In

    clikc -> click 

  4. +++ b/source/en/views-block.txt
@@ -27,38 +27,38 @@ only.
-. In the Title section, click on _Title: Recipes_. Change _For This block
-(override)_ the Title to "New Recipes" and click _Apply (this display)_.
+. In the Title section, click _Title: Recipes_. Change _For This block
+(override)_ the Title to "New Recipes" and select _Apply (this display)_.

    I think this still needs some attention. Here's what I changed it to:

    . In the Title section, click _Title: Recipes_. In the pop-up window, under
_For_, select _This block (override)_. Change the Title to "New Recipes" and
click _Apply (this display)_.

    I think this is more accurate. If you think we need to change it more, please feel free to make a new patch for this section. 

  5. +++ b/source/en/views-duplicate.txt
@@ -80,7 +80,8 @@ new path "recipes" in the pop-up then _Apply_. Then via the _Menu_ pop-up change
 . Roll out the _Advanced_ sections. In the _Other_ section change _Use AJAX: No_
-to "Yes": click on "No" and choose for using AJAX in the pop-up then _Apply_.
+to "Yes" by clicking _No_ and select to use AJAX in the pop-up that appears.
+Then click _Apply_.

    I took a look at the UI for this... I think this is more accurate, so I put this in (if you think it needs another edit, please make a new patch for this file):

    . Roll out the _Advanced_ sections. In the _Other_ section change _Use AJAX: No_
to "Yes" by clicking _No_ and checking _Use AJAX_ in the pop-up that appears.
Then click _Apply_.

Anyway... I made these small changes and applied the patch, and as far as I am concerned, this issue is fixed. THANKS very much!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.