Problem/Motivation

The description of a module on the Extend page, describes what the module does.
Not all module descriptions on the Extend page follow the common format, as described in the Help text standard.

Proposed resolution

Change the descriptions in the modules .info.yml files for the stable modules so that they are correct, consistent, and follow the same format.
Experimental modules should have their own issues assigned because their functionality is still changing too much to hold up this issue in general.

Remaining tasks

  • Compare the module description text of each module with its help text. The help texts have already been reviewed and generally the beginning of the About section provides a good wording of what the module does.
  • Check the format of the description text. Does it
    • start with a verb, third-person singular (Does, Provides, etc.);
    • is it short and concise;
    • does it end with a full stop (.)?

User interface changes

This is a UI text change.

API changes

None.

Data model changes

None.

Files: 

Comments

ifrik created an issue. See original summary.

ifrik’s picture

Issue summary: View changes
ifrik’s picture

Assigned: ifrik » Unassigned
Parent issue: » #2499495: [meta] Review UI text for D8 core modules

I've checked and updated the modules Action to Forum so far, but left out the filter module because the hook_help text of that needs updating anyway #2570359: Update the hook_help for the filter module again.

ifrik’s picture

FileSize
11.25 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,720 pass(es). View
3.56 KB

I've done Help to Search.

ifrik’s picture

Status: Active » Needs review
FileSize
32.87 KB
FAILED: [[SimpleTest]]: [PHP 5.5 MySQL] Unable to apply patch 2570985-ui-text-extend-page-5.patch. Unable to apply patch. See the log in the details link for more information. View

I've checked all module descriptions on the Extend page against the hook_help texts and formatting standards, and edited them in the modules *.info.yml files.

I've also added or removed some single quotation marks around the name in the *.info.yml file for consistency.

Status: Needs review » Needs work

The last submitted patch, 5: 2570985-ui-text-extend-page-5.patch, failed testing.

The last submitted patch, 5: 2570985-ui-text-extend-page-5.patch, failed testing.

ifrik’s picture

Some code from reviewing some other patch got mixed in here.

ifrik’s picture

ifrik’s picture

Status: Needs work » Needs review
FileSize
26.72 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,706 pass(es). View

Status: Needs review » Needs work

The last submitted patch, 10: 2570985-ui-text-extend-page-9.patch, failed testing.

Status: Needs work » Needs review

The last submitted patch, 4: 2570985-ui-text-extend-page-4.patch, failed testing.

ifrik’s picture

isntall’s picture

patch has been re-submitted and is running.

ifrik’s picture

Bojhan’s picture

Issue tags: -Needs usability review

I am not really sure about this. This could use some more rationale why this particular wording was used - quite a few get more lengthy and verbose. Focusing on what the "thing" delivers rather than a goal/task oriented description.

ifrik’s picture

Some of the descriptions currently aren't in the format of "Foo does something", and for a few the descriptions are simply not correct.
But I can try to shorten those ones that ended up too long, and then give a better overview.

ifrik’s picture

Issue tags: +Needs usability review
FileSize
26.41 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,903 pass(es). View
11.37 KB

I've shortened the texts so that in general they are not longer then 80 or maybe 90 characters.

Here's an overview over why what was rewritten: usually because it they didn't fit the format, because they weren't quite correct, or very different from the hook_help texts which have been extensively reviewed in the last 2 years and which always start with a description whath the module does.

Actions: format as a sentence, consistent with help.
Activity tracker: consistent with help, more accurate description
Aggregator: changed the verbs, making it consistent with help instead of repeating the module name as a verb.
Ban: Current text can be misunderstood as banning the use of specific IP addresses in the site, but it bans visits from these IP addresses
Block: More accurate description of what the module does, and removed the sentence explaining what blocks are.
CKEditor: formated as a sentence
Comment: removed "discuss" because that's just one way comments can be used.
Config Manager: replaced manage with "import and export" because it's a new concept, and manage is already part of the name
Contact: More accurate description of what the module does.
Contextual links: reworded consistent with the help and removing the duplication of "contextual links"
Custom Block: added the creation of block types instead of only referring to block and removed the reference to the user interface because that's less needed here.
Custom menu links: removed custom from the description because it's obvious that the links are custom if a user has created them.
Database logging: removed "records" because that is part of the logging
Field: Formulated as a sentence
Field UI: Formulated as a sentence
Filter: Rewritten to mention that it's text formats that are used for filtering
Forum: Rewritten consistent with the hook_help text because the module doesn't provide any forums, only the ability to create them
History: Rewritten consistent with the hook_help text, and added the marking as new/updated as functionality provided.
Internal Dynamic page cache
Node: Rewritten to be more accurate and consistent with the hook_help text
RDF: Shortened because it was very long
Responsive image: shortened
Search: Rewritten because the current text only refered to keyword search
Shortcut: Rewritten so that it can be more easily understood
Statistics: Rewritten to be a bit more accurate and consistent with the hook_help text
Syslog: Rewritten to be more descriptive and consistent with the hook_help.
System: Rewritten to be more descriptive
Text editor : Rewritten to be more accurate.
Toolbar: Rewritten to be consistent with the hook_help
Update manager: Rewritten to be consistent with the hook_help and
User: Rewritten to include the user roles and permissions
views: Rewritten to be consistent with hook_help

Migrate and Migrate drupal: Rewritten so that they are consistent with each other

Field type modules: Rewritten so that they are consistent with each other

Multilingual modules: Rewritten so that they are consistent with each other

yoroy’s picture

  1. +++ b/core/modules/dynamic_page_cache/dynamic_page_cache.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Caches pages for all users, handling dynamic content correctly.'
    

    "handling dynamic content correctly", I don't know what this means. It suggests that without it, dynamic content is handled incorrectly. Is that true?

  2. +++ b/core/modules/editor/editor.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides a framework that other modules can use to add toolbars or other means to format content.'
    

    "Provides ways to show toolbars for formatting content."? Or is that too simplified?

  3. +++ b/core/modules/field/field.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows the definition of custom data fields for entity types.'
    

    Maybe Enables instead of Allows? "Allows" smells of permissions.

  4. +++ b/core/modules/filter/filter.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows administrators to configure text formats to prepare content for display.'
    

    …configure text formats that prepare content for display.

ifrik’s picture

FileSize
1.93 KB
26.38 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 114,341 pass(es). View

I changed those for descriptions.

The Text editor module makes it possible for contrib modules to add not only toolbars but also other ways of formatting text (even though I can't quite visualize what that might be at the moment) so kept that formulation a bit broader.

Sam152’s picture

Status: Needs review » Needs work

Great work on making things consistent, good to see. Few things I suggest or picked up on:

  1. +++ b/core/modules/datetime/datetime.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines  Date fields that store dates and times.'
    

    Double space and capital?

  2. +++ b/core/modules/dynamic_page_cache/dynamic_page_cache.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Caches pages incl. those with dynamic content for all users.'
    

    There aren't any abbreviations elsewhere?

  3. +++ b/core/modules/rdf/rdf.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Enriches content with metadata (relationships, attributes etc.) for other applications (search engines, aggregators etc.).'
    

    Are the etc.'s required? Why not mention the RDF spec instead of quoting the use cases?

  4. +++ b/core/modules/serialization/serialization.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides a service for (de)serializing data to/from formats such as JSON and XML.'
    

    Normalizing is the terminology used to reverse serializing. I'd also stick to "to and from" instead of to/from.

  5. +++ b/core/modules/statistics/statistics.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Logs how often content of the site is viewed.'
    

    Should this be "content on"?

  6. +++ b/core/modules/telephone/telephone.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines fields that contain telephone numbers.'
    
    +++ b/core/modules/text/text.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines short and long text fields with optional summaries.'
    

    Sticking with the theme should these be "Provides a field type for..."

  7. +++ b/core/modules/update/update.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Checks for updates, and allows administrators to manage them through an interface.'
    

    Extra comma?

ifrik’s picture

Status: Needs work » Needs review
FileSize
26.9 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 114,483 pass(es). View
101.76 KB

Thanks Sam152 for the review.
I've fixed most of them accordingly.
About the serialization: We use serialization and deserialization in the help text; and "(de)serialization" was the description provided by the person writing the module. I've tried to fix this by not using serialization at all since it's already in the module name anyway.
I left the text field because it would just get convoluted, and "text field" is a phrase that's used in other contexts as well.

jhodgdon’s picture

Status: Needs review » Needs work

Wow. I can tell a lot of work went into this, but it still needs a lot more work to be more consistent. Plus, there are some grammatical problems.

Here is a quick run-through with some things to fix:

  1. +++ b/core/modules/ckeditor/ckeditor.info.yml
    @@ -1,6 +1,6 @@
    -description: "WYSIWYG editing for rich text fields using CKEditor."
    +description: 'Provides a visual text editor and adds a toolbar to text fields.'
    

    It seems like it should still mention that specifically it is the CKEditor editor that is provided. This is a 3rd-party editor that people may be familiar with, and other (contrib) modules may still provide other editors.

  2. +++ b/core/modules/comment/comment.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows users to comment on published content.'
    

    Hm. Is it actually not possible to comment on unpublished content? I have no idea.

  3. +++ b/core/modules/contextual/contextual.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides quick access to tasks related to elements on a page.'
    

    Perhaps this should be:
    elements of a page
    or
    parts of a page
    or
    ... hm, not sure. It's just not really clear what it means from this description, do we have a better description in the hook_help() perhaps?

  4. +++ b/core/modules/dblog/dblog.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Logs system events in the database of the site.'
    

    database of the site
    =>
    site database

  5. +++ b/core/modules/editor/editor.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides a framework for other modules to add toolbars or other means to format content.'
    

    ... to format content... hm...

    how about

    Provides a framework for other modules to add text editors and toolbars to formatted text fields.

  6. +++ b/core/modules/entity_reference/entity_reference.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines fields that contain links to other content, users etc. within the site.'
    

    Um. This is ... not good. The punctuation is not great, for one thing. Maybe rewrite this one?

  7. +++ b/core/modules/field/field.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Enables the definition of custom data fields for entity types.'
    

    So you're using the word "entity" all over the place, how come "entity reference" cannot keep using it too?

    Also, really this should have API in the description. It is just for programmers and this is lost in the change here.

  8. +++ b/core/modules/field_ui/field_ui.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides an user interface for managing and displaying fields.'
    

    an user => a user

    But the UI is really for the management of fields, and their display and editing properties. The UI is not needed in order to "display fields", it is only for "manage". This is misleading.

  9. +++ b/core/modules/file/file.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines fields that contain files.'
    

    No, it defines a field type, not "fields".

  10. +++ b/core/modules/filter/filter.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows administrators to configure text formats that prepare content for display.'
    

    Everywhere else the descriptions say "users" not "administrators".

  11. +++ b/core/modules/hal/hal.info.yml
    @@ -1,4 +1,4 @@
    -name: 'HAL'
    +name: HAL
    

    Why take the quotes off here? You've added them everwhere else.

  12. +++ b/core/modules/history/history.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Records which content a user has viewed and marks it as new or updated.'
    

    actually it does this for all users, not "a user".

  13. +++ b/core/modules/language/language.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows administrators to configure the languages available in the site.'
    

    administrators => users

  14. +++ b/core/modules/menu_ui/menu_ui.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides an interface for managing menus.'
    

    interface => user interface

  15. +++ b/core/modules/options/options.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines fields with select lists, checkboxes or radio buttons to select values from a fixed list of options.'
    

    needs comma before "or"

  16. +++ b/core/modules/path/path.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows users to specify a custom URL for an existing internal path.'
    

    I would make this plural
    custom URLs
    paths

  17. +++ b/core/modules/quickedit/quickedit.info.yml
    @@ -1,6 +1,6 @@
    -description: 'In-place content editing.'
    +description: 'Allows users to edit field content without visiting a separate page.'
    

    separate from what?

    I liked the previous description better.

  18. +++ b/core/modules/search/search.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows administrators to create search pages based on plugins provided by other modules.'
    

    administrators => users

  19. +++ b/core/modules/serialization/serialization.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides a service to converts data structure to and from formats such as JSON and XML.'
    

    converts => convert

    actually the grammar of this needs more fixing than that!

  20. +++ b/core/modules/statistics/statistics.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Logs how often content of the site is viewed.'
    

    hm. not really "how often", more like "how many times" I think?

  21. +++ b/core/modules/syslog/syslog.info.yml
    @@ -1,6 +1,6 @@
    +description: "Logs events by sending messages to the logging facility of the web server."
    

    This should not be using "" quotes I think?

  22. +++ b/core/modules/system/system.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides user interfaces for core systems and their configuration.'
    

    um, isn't it all configuration? This seems redundant.

  23. +++ b/core/modules/telephone/telephone.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines fields that contain telephone numbers.'
    

    no, it defines field types, not fields.

  24. +++ b/core/modules/text/text.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines short and long text fields with optional summaries.'
    

    field types not fields

  25. +++ b/core/modules/toolbar/toolbar.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides an administration toolbar which displays tabs and trays provided by modules.'
    

    which -> that

  26. +++ b/core/modules/tour/tour.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides guided tours of the site interface.'
    

    Actually it only displays them, as modules provide them.

  27. +++ b/core/modules/update/update.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Checks for updates and allows administrators to manage them through an interface.'
    

    interface -> user interface

  28. +++ b/core/modules/views/views.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows users to fetch information from the database and to display it in different formats.'
    

    Um. Not really.

ifrik’s picture

FileSize
26.85 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,487 pass(es). View
11.95 KB

Thanks for the review.
I'm don't quite sure why some of the modules in the field type section now define field types while others define fields; or whether I should change all of the accordingly.

I've done nearly all according to the comments.

3. I added "direct" - for the rest the description based on the hook_help.

5. The toolbars etc. are added to text fields in general (not formatted ones), so I changed that accordingly.

6. Since "entity" is already in the name, I was trying to sneak in a bit more explanation, but in fact the main point is that it's to something that is within the site.

7. Added API back into the description.

11. I had asked during the sprint why some of the name had single quote around them and other not, and the answer was that it was convention to put them around several words, but not needing them around single words, so I fixed what I had done - and apparently that one as well.

17. That's wording used in the hook_help, but I understood it as not having to go to another edit page.

28. Reworded according to the hook_help.

ifrik’s picture

Status: Needs work » Needs review
jhodgdon’s picture

Regarding your comments in #26, ...

All of the modules that define field anythings are defining field types, field widgets, and/or field formatters, so I think all of the wording should say "field types".

Regarding item 5, I believe that the text field must have a text format associated with it, in order for the Editor module to add a toolbar/editor to the field, because in the UI for the Editor module, it allows you to associate a particular editor/toolbar with a particular text format. So a field without a text format would not get an editor, right?

I haven't looked at the patch yet. Want to fix those two items and I'll give it a good review again? Thanks!!

ifrik’s picture

FileSize
26.88 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,239 pass(es). View
3.31 KB

I've changed the Field type module descriptions accordingly.

About the text editor: It's true that a toolbar (or any other functionality) should only be displayed if also the text format is set up to allow this, but if I get it correctly the editor module just provides the framework for other modules to use.

The description now very closely follows the wording in the hook_help.

jhodgdon’s picture

Regarding Editor, I looked at the code for that module, and it definitely only modifies text-with-text-format boxes. It cannot be used to add an editor to plain text boxes that do not have a text format on them. The UI also only allows you to attach editors to particular text formats.

If the hook_help implies that it can do something other than that, it needs to be changed too.

ifrik’s picture

How about Provides a framework to associate text formats with text editors and toolbars.?

That's pretty close to what it was anyway.

jhodgdon’s picture

That seems fine... wonder if it's clearer if the "associates" goes the other way:

Provides a framework to associate text editors and toolbars with text formats.

ifrik’s picture

FileSize
26.87 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,479 pass(es). View
504 bytes

That's exactely what I had been wondering about as well :-)

jhodgdon’s picture

Status: Needs review » Needs work

On a different issue, @Bojhan suggested removing "site" where possible... Looking at these:

  1. +++ b/core/modules/action/action.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides tasks that can be executed by the system on specfic events.'
    

    I think we need to keep "by the system" here, so this seems fine to me.

    Although ...

    The Configure page description from the other patch/issue seems to have a better description. Something like:

    Allows configuration of tasks to be executed in response to events

    might be better?

  2. +++ b/core/modules/ban/ban.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Enables administrators to ban visits to the site from specific IP addresses.'
    

    could lose

    to the site

    here

  3. +++ b/core/modules/dblog/dblog.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Logs system events in the site database.'
    

    could lose "site" here, although I think maybe I suggested adding it ;)

  4. +++ b/core/modules/dynamic_page_cache/dynamic_page_cache.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Caches pages including those with dynamic content for all users.'
    

    I think "including those with dynamic content" needs to be surrounded by commas?

  5. +++ b/core/modules/entity_reference/entity_reference.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines field types that contain links to other entities within the site.'
    

    could drop "within the site"

  6. +++ b/core/modules/filter/filter.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows userss to configure text formats that prepare content for display.'
    

    typo: userss

  7. +++ b/core/modules/language/language.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows users to configure the languages available in the site.'
    

    Could make this even more concise:

    Allows users to configure available languages

  8. +++ b/core/modules/migrate/migrate.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides a framework to migrate data, usually from an external source into the site.'
    

    As a note, here I think we need the "into the site" part, to clarify that this module does not help you migrate data out of the site (it doesn't).

    Maybe this should be though:

    Provides a framework for migrating data into the site

  9. +++ b/core/modules/migrate_drupal/migrate_drupal.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides a framework to migrate data from older Drupal sites into the site.'
    

    Similarly, I think this would be slightly better wording as:

    Provides a framework for migrating data from previous versions of Drupal into the site

  10. +++ b/core/modules/node/node.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Manages the creation, configuration, and display of the main site content.'
    

    I kind of think "site" is good here.

  11. +++ b/core/modules/options/options.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines field types with select lists, checkboxes, or radio buttons to select values from fixed lists of options.'
    

    or => and ?

  12. +++ b/core/modules/path/path.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows users to specify custom URLs for existing internal paths.'
    

    specify => create?

  13. +++ b/core/modules/rest/rest.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides a framework for exposing REST resources on the site.'
    

    could lose "on the site"

  14. +++ b/core/modules/serialization/serialization.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides a service to convert data structure to and from formats such as JSON and XML.'
    

    How about losing the word "structure" here?

    Better wording:

    Provides a service for converting data to and from formats such as JSON and XML

  15. +++ b/core/modules/shortcut/shortcut.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows users to create sets of shortcut links to pages within the site.'
    

    Could drop "to pages within the site" or at least drop "to pages"... we may want to leave "within the site" to make it clear it's only internal? or is it?

  16. +++ b/core/modules/statistics/statistics.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Logs how often content of the site is viewed.'
    

    could drop "of the site"

  17. +++ b/core/modules/telephone/telephone.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines fields types that contain telephone numbers.'
    

    fields types that contain => a field type that contains

  18. +++ b/core/modules/tour/tour.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Displays guided tours of the site interface.'
    

    probably site is OK here

  19. +++ b/core/modules/views/views.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Provides a back end to fetch information from the database and to display it in different formats.'
    

    I really like this one!

jhodgdon’s picture

Actions... discussing this on another issue also... maybe it should say (to avoid passive voice):

Allows configuration of tasks for the system to execute in response to events.

ifrik’s picture

Status: Needs work » Needs review
FileSize
26.75 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,635 pass(es). View
8.08 KB

Shortcuts are really only internal, so I left that, and for the rest I took up all the suggestions.

I will be offline mostly for the next days, so if it needs any more work, it would be good if somebody else could do that.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community
Issue tags: +rc deadline
FileSize
26.76 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 114,032 pass(es). View
1.27 KB

https://groups.drupal.org/node/484788 Apparently this needs to be "rc deadline" because it changes translatable UI text strings

This all looks great to me! I found 3 little typos, so I fixed those (ifrik is away) and am marking the patch RTBC.

  1. +++ b/core/modules/action/action.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows configuration of tasks for the system to execute in response to events'
    

    To be consistent with the rest, this needs a . at the end

  2. +++ b/core/modules/shortcut/shortcut.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Allows users to create sets of shortcut within the site.'
    

    shortcut -> shortcuts

  3. +++ b/core/modules/telephone/telephone.info.yml
    @@ -1,6 +1,6 @@
    +description: 'Defines a field type that contain telephone numbers.'
    

    contain -> contains

xjm’s picture

Status: Reviewed & tested by the community » Needs work
  1. +++ b/core/modules/ban/ban.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Enables banning of IP addresses.'
    +description: 'Enables users to ban visits from specific IP addresses.'
    

    "Enables users to X" is a bit strange. Maybe just "Allows" instead?

  2. +++ b/core/modules/basic_auth/basic_auth.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Provides the HTTP Basic authentication provider'
    +description: 'Provides an HTTP Basic authentication provider.'
    

    Still providing a provider. ;) but I guess that this is fine.

  3. +++ b/core/modules/block/block.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Controls the visual building blocks a page is constructed with. Blocks are boxes of content rendered into an area, or region, of a web page.'
    +description: 'Allows users to configure blocks and to place them in the regions of a theme.'
    

    We are losing the description of what a "block" is here. I actually think this is pretty important since usability studies always surface that "block" does not mean anything to normal people. See: https://www.drupal.org/files/mental-model-big.png

  4. +++ b/core/modules/ckeditor/ckeditor.info.yml
    @@ -1,6 +1,6 @@
    -description: "WYSIWYG editing for rich text fields using CKEditor."
    +description: 'Provides a visual text editor and adds a toolbar to text fields using CKEditor.'
    

    I think "WYSIWYG" is actually useful information as well, because that would tell me what it is exactly, whereas the current description doesn't entirely make it clear that this is how I get my WYSIWYG on. Maybe put that in parentheses after "visual text editor"?

  5. +++ b/core/modules/contextual/contextual.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Provides contextual links to perform actions related to elements on a page.'
    +description: 'Provides direct and quick access to tasks related to areas of a page.'
    

    I also think losing the word "links" here is not good. "Provides direct and quick access" doesn't help me understand that this allows me to stick little menus of links on stuff on my page .

  6. +++ b/core/modules/editor/editor.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Provides a means to associate text formats with text editor libraries such as WYSIWYGs or toolbars.'
    +description: 'Provides a framework to associate text editors and toolbars with text formats.'
    

    This one I think it's okay to remove "WYSIWYG" so long as we keep it for CKEditor. The fact that CKEditor requires this one will make it clear.

  7. +++ b/core/modules/entity_reference/entity_reference.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Provides a field that can reference other entities.'
    +description: 'Defines field types that contain links to other entities.'
    
    +++ b/core/modules/field/field.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Field API to add fields to entities like nodes and users.'
    +description: 'Provides the Field API to add fields to entities.'
    

    I also think throwing users a bone about what an "entity" is is valuable.

    Also, in the first hunk, I think ER defines only one field type, not multiple field types?

  8. +++ b/core/modules/file/file.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Defines a file field type.'
    +description: 'Defines field types that contain files.'
    
    +++ b/core/modules/image/image.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Defines an image field type and provides image manipulation tools.'
    +description: 'Defines field types that contain image files and provides tools to configure their display.'
    

    Does it actually define multiple field types? I thought it was just the one, in both cases. I'll look on the issue to see if there's an explanation for this.

  9. +++ b/core/modules/path/path.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Allows users to rename URLs.'
    +description: 'Allows users to create custom URLs for existing internal paths.'
    

    I'm not sure about "existing internal paths"; the word "internal" seems misleading or confusing in context. It's also required to provide the path alias for e.g. a node. Maybe "existing paths on the site"?

  10. +++ b/core/modules/system/system.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Handles general site configuration for administrators.'
    +description: 'Provides user interfaces for core systems.'
    

    Hmm, system does a lot more than that.

  11. +++ b/core/modules/toolbar/toolbar.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Provides a toolbar that shows the top-level administration menu items and links from other modules.'
    +description: 'Provides an administration toolbar that displays tabs and trays provided by modules.'
    

    Not sure about this one... modules don't have to define tabs and trays; just the links.

  12. +++ b/core/modules/views/views.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Create customized lists and queries from your database.'
    +description: 'Provides a back end to fetch information from the database and to display it in different formats.'
    

    I think the word "lists" is important. Also, I don't think we should say it provides a back end for fetching info from the database; that sounds like a DB driver, and the information can also come from other sources than a database.

I'd be alright with splitting these less clear-cut strings into a separate issue and committing the rest first so that we can improve as many strings as possible before RC.

Bojhan’s picture

Version: 8.0.x-dev » 8.1.x-dev
Issue tags: -Needs usability review

This needs a lot of work, and wouldn't consider this a key improvement for 8.0.0 I am going to move this to 8.1

ifrik’s picture

Status: Needs work » Needs review
FileSize
26.78 KB
5.5 KB

I've taken up most of the proposals from comment #38, also re-reading through the previous comments.
I've also edited the description of the newly added Inline Form Errors module

1. File types: I've checked them and File, Image, Link and Telephone only provide one type, while the others provide several types. Entity Reference is not listed on the Extend page anymore.

2. System: We had previously removed the mentioning of configuration as redundant from the description. Basically we need a description that says something like "Does lots of things and can't be uninstalled anyway".

3. Field: In an earlier comment it was pointed out that Field API is only for developers, so I think the mentioning of Entity here doesn't make it anymore complicatied. As with the Blocks module: it would be great if the hook_help text could be accessible even if the module is not enabled, because that gives a detailed explanation.

4. Views: The text is the one we also use in the hook_help text to describe what the Views module does, so we might need to change that as well. From which other sources can the information come? About "lists": Views itself uses "lists" only as one of several formats (besides table, grid, and whatever other formats contrib modules provide) so "lists" is to restricted here, but could be added as an example.

5. Blocks: The descriptions on the Extend page only describe briefly what the module does, without explaining underlying concepts. If we want to add such explanations, then there are probably more modules for which that would make sense. (Ideally, the help pages that have all this information should be accessible for uninstalled modules as well...)
In any case, the text for the Block module is currently misleading. Blocks are not only used for content, but also for configuration (such as the site name), forms (user login) etc.; and "boxes" is confusing because there also is the Box module. So we need a better explanation what a block is in D8.

jhodgdon’s picture

Hopefully @Bojhan can comment/review...

no_angel’s picture

Assigned: Unassigned » no_angel
Status: Needs review » Needs work
Issue tags: -Barcelona2015, -rc deadline
no_angel’s picture

Hi @jhodgdon,

Not sure if this is the correct place to post this:

I've been working on :Update the UI texts for the Custom Block module and ran across this issue.

Based on Comment 40 1. File types: I've checked them and File, Image, Link and Telephone only provide one type, while the others provide several types. Entity Reference is not listed on the Extend page anymore.

I'm not sure if it should be but it's not listed on the Help page either.

Found this issue and re-tested the patch https://www.drupal.org/files/issues/entity_reference_help-2029751-29.patch and it now fails.

Can you please advise if that patch needs to be re-rolled and the next steps for this issue.

Sorry if I'm way off track here, I tend to over re-research everything.

@ifrik if you are working on this issue, go ahead and un-assign me.

Cheers

jhodgdon’s picture

Right, there is no Entity Reference module now. It is just a core Field type [note: typo in #40 and #43 -- they are *field* types not *file* types]. So the Entity Reference help page doesn't exist, and the Entity Reference field is currently documented in the Field help page (module Field, file field.module, function field_help()), along with other Core-provided fields.

So no, we don't want to revive that other issue about Entity Reference help. It's not a module any more, and so there is no Entity Reference help per se.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.0-beta1 was released on March 2, 2016, which means new developments and disruptive changes should now be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

yoroy’s picture

Issue tags: +ux-interfacetext
ifrik’s picture

Issue tags: +DevDaysMilan
ifrik’s picture

Assigned: no_angel » Unassigned
Issue tags: +String change in 8.2.0, +sprint

I'll be working on this during DevDaysMilan

ifrik’s picture

I'm not sure why this was moved to Needs work in #43 because the comment did not really seem to be about this issue.

Inline Form error is now an experimental issue. Therefore the patch did not apply anymore, but it has its own issue #2702545: Edit the Inline Form Error module description so I removed it as the only change between patch 40 and 49.

Status: Needs review » Needs work

The last submitted patch, 49: 2570985-ui-text-extend-page-49.patch, failed testing.

ifrik’s picture

Status: Needs work » Needs review

Random test bot fail.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Manjit.Singh’s picture

FileSize
173.52 KB

This issue is to update the module description on extend page but don't know why i am seeing the bit of layout change. Am i doing something wrong here ?
check the screencast.

Manjit.Singh’s picture

Issue tags: +Dublin2016

Status: Needs review » Needs work

The last submitted patch, 49: 2570985-ui-text-extend-page-49.patch, failed testing.

ifrik’s picture

Issue tags: +Barcelona2015

Added the Barcelona tag again, because there was no reason to remove it,

The last submitted patch, 49: 2570985-ui-text-extend-page-49.patch, failed testing.

chipway’s picture

I am working on this issue in DrupalCon Dublin2016.
I will try to apply https://www.drupal.org/files/issues/2570985-ui-text-extend-page-49.patch
[EDIT] patch doesn't apply against 8.3.x.

then I will re-roll it https://www.drupal.org/contributor-tasks/reroll

chipway’s picture

Status: Needs work » Needs review
FileSize
26.26 KB

I re-rolled rebased the patch against 8.3.x.
No conflict after few trials (got it from commit 5dd8636e97) then rebased on 8.3.X, and same file size.

Status: Needs review » Needs work

The last submitted patch, 59: 2570985-59.patch, failed testing.

chipway’s picture

I have to change the test and will do it next week.

chipway’s picture

Status: Needs work » Needs review
FileSize
27 KB

Here is the patch with descriptions changes from https://www.drupal.org/node/2570985#comment-11678809 and Test change.
@Manjit.Singh, I think that the display layout changes a little because of shorter descriptions text and responsive display. I propose to not change css or layout as it fits when I try it on several view width.

mradcliffe’s picture

Thank you for the past couple of patches, @chipway.

Could you provide an interdiff between the patches from #49 to #59 and from #59 to #62? An interdiff helps reviewers look at the changes between patches and makes it easier to check the intended changes from what you worked on.

chipway’s picture

Thanks @mradcliffe,
here are the interdiff files, but I do not know why there is no difference between 2570985-ui-text-extend-page-49.patch and 2570985-59.patch, while 2570985-ui-text-extend-page-49.patch didn't apply on 8.3.x, and 2570985-59.patch applies. Any idea of the reason?

mradcliffe’s picture

I think it's because the patch didn't have any changes and could be applied to 8.3.x fine as-is from the 8.2.x version.

Thank you for posting interdiffs.

Bojhan’s picture

The descriptions for Views are a little diffuse. Its unclear which one is about powering the API's and which one allows you to create (with clicks) the views?

chipway’s picture

Would these be better for views and views_ui?

/core/modules/views/views.info.yml
+description: 'Provides the Views API to fetch information from the database and to display it in different formats.'
or
+description: 'Provides the Views API to fetch information of entities from the database and to display it in different formats.' (which is closer to the help text).

/core/modules/views_ui/views_ui.info.yml
+description: 'Provides a user interface for creating and managing views.'

chipway’s picture

Status: Needs review » Needs work

Waiting for review of https://www.drupal.org/node/2570985#comment-11702267, then will need to change the patch.

lomasr’s picture

FileSize
52.4 KB
39.54 KB

Patch in #62 applied cleanly . Please see before & after screens.

chipway’s picture

Status: Needs work » Needs review
FileSize
27.01 KB
889 bytes

Little update including #67.

ifrik’s picture

Status: Needs review » Reviewed & tested by the community
Issue tags: -String change in 8.2.0 +String change in 8.3.0

Thanks,
I think that's now really all done.

I'll make separate issues for the new experimental modules. They need some work anyway to fix their help texts, so the module descriptions can be done together with that.

lomasr’s picture

@ifrik I think you have created duplicate issues. 2830832 # 2830833 have same titles. As per the Issue scope https://www.drupal.org/core/scope . I think we don't need new issues. I have added changes for Content Moderation , Place Block.

Please review

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 73: 2570985-72.patch, failed testing.

ifrik’s picture

Thanks for fixing the duplication.

I was trying to avoid that with every new experimental module we start delaying this issue further, and those modules need work on their UI texts anyway.

Can you make an interdiff for the new changes?

chipway’s picture

I agree with ifrik.
We should fix this issue and use new issues for experimental modules, or we will never fix this one as new experimental modules will continue to appear.

tkoleary’s picture

Bojhan’s picture

Status: Needs work » Reviewed & tested by the community

Back to RTBC, I think we need to either get this in or split this up. This patch is way too hard to review and discuss.

chipway’s picture

FileSize
1.84 KB

I added interdiff-2570985-70-72.txt for better readability for myself and others.

@lomasr, Thank you for your help, but I think that your patch is out of the scope of this issue because the current issue doesn't deal with hook_help. On another hand, Content Moderation & Place Block will still be experimental in 8.3. I would suggest opening a new issue or adding this to another existing issue.

@Bojhan, Thank you. I agree. I would suggest to stop the current issue at #70.

xjm’s picture

Status: Reviewed & tested by the community » Needs work

Thanks everyone for continuing to work on this. I agree with @Bojhan that we should split this issue up since the scope is too hard to complete in one patch. Edit: the descriptions that are being rewritten are each about a separate concept, so per https://www.drupal.org/core/scope it makes sense to have issues to discuss conceptual groups of them in their own right. For simply fixing verb forms and punctuation, a single patch is correct, but best to not mix the two.

  1. +++ b/core/modules/action/action.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Perform tasks on specific events triggered within the system.'
    +description: 'Allows configuration of tasks for the system to execute in response to events.'
    

    This item is a noun salad. Is "for the system" necessary? Can we just say "Allows configuration of tasks that will be executed in response to events"?

  2. +++ b/core/modules/block/block.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Controls the visual building blocks a page is constructed with. Blocks are boxes of content rendered into an area, or region, of a web page.'
    +description: 'Allows users to configure blocks and to place them in the regions of a theme.'
    

    I still think this is a regression. Let's please add a parenthetical something like:

    "Allows the user to configure blocks (boxes of content) and to place them in regions of a theme."

    I see @ifrik's earlier point that it's not always content, but I think enough are content or content-like that it gets the point across. And I don't think we should remove the word "boxes" just because there's a contrib module called that, if it helps the user understand what a block is.

  3. +++ b/core/modules/editor/editor.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Provides a means to associate text formats with text editor libraries such as WYSIWYGs or toolbars.'
    +description: 'Provides a framework to associate text editors and toolbars with text formats.'
    

    Losing the keyword WYSIWYG here again. Let's just say "text editors (like WYSIWIGs)".

  4. +++ b/core/modules/link/link.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Provides a simple link field type.'
    +description: 'Defines a field type that contain internal or external URLs.'
    

    This includes a grammatical error ("contain" is the wrong verb form).

  5. +++ b/core/modules/syslog/syslog.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Logs and records system events to syslog.'
    +description: 'Logs events by sending messages to the logging facility of the web server.'
    

    I think this description actually is less clear and is longer than it needs to be. Maybe:
    "Logs events to the web server's system log."

  6. +++ b/core/modules/telephone/telephone.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Defines a field type for telephone numbers.'
    +description: 'Defines a field type that contains telephone numbers.'
    

    This description is also confusing. It sounds like you install this module and get some telephone numbers on your site. (The word "contains" for other field types confused me when I read it, actually.)

    I think the previous description was fine.

  7. +++ b/core/modules/views/views.info.yml
    @@ -1,6 +1,6 @@
    -description: 'Create customized lists and queries from your database.'
    +description: 'Provides the Views API to fetch information from the database and to display it in different formats.'
    

    Elsewhere, we call an API a "framework". Do we need to repeat the name of the module in the description? We don't do that elsewhere

We could split this into one patch for the field type descriptions, another for modules that only provide APIs, etc. We could also split out the specific descriptions that are tricky, like those for views and blocks. I'd be okay with removing description changes I've raised concerns with from this patch and putting them in a separate issue. This patch does include a lot of great improvements that we could get in now and not block on the trickier ones.

tkoleary’s picture

I think in general we should be putting the functionality provided to users first, in the form of "Users can". Beginning with a verb when the subject is the user, not the module leads to confusion, as does using roles (administrators can) since those can be changed.

In the event there is no action the user can take with the module, we can start with a verb which should always create a sentence in which the module name is assumed. eg.

[Syslog] logs events to the web server's system log.

Where there is a clear task for the user but there also needs to be a clear description of the underlying function we could begin a second sentence with "The module..." eg.

Users can create customized lists, tables or grids of content. The module queries the database and re-formats the content in a variety of formats.

Separating User and Module specific information frees us up to be more everyday with the former, and more technical with the latter.

@xjm, @lomasr

#1 Better still, also remove the passive voice:

Users can create tasks that the module will execute in response to events.

#2

Users can create blocks of content and place them in regions of the page. The module provides a list of regions in each theme and the blocks they contain.

#3 This is the key user benefit.

Users can choose text editors, WYSIWYG toolbars and text formats for different kinds of content.

#4

Users can create a link field. The module defines a field type for internal or external URLs.

#5 Agree with xjm

Logs events to the web server's system log.

#6 Leaves out the key benefit

Users can add a telephone field that phones can recognize. The module defines a field type for the HTML5 'telephone' tag.

xjm’s picture

I agree we should avoid the passive voice, though actually "Allows users to..." is not passive voice. Probably Kevin is getting at the notion that "Allows" is a weak verb or that we should avoid verb + infinitive. (Passive voice would be "Users are allowed to...")

Users can create customized lists, tables or grids of content. The module queries the database and re-formats the content in a variety of formats.

FWIW, I think this is too long and less clear.

I also find the proposed sentences with "Users can" confusing, because if I were looking over the module page, it wouldn't be clear to me that the module is what makes it so that the users can do those things. So I think the standardization agreed in the summary, of starting with a third-person present tense indicative verb that has the module as the subject, is actually the best approach.

Can someone remove the changes to descriptions related to #80 and #81, as well as add a postponed followup for them, so we can review what's left and try to get some of the improvements that have consensus in? Thanks!

ifrik’s picture

Hi tkoleary,

we have a clear standard for how to word these descriptions as outlined in the Help Text Standards, and this has been repeatedly reviewed by members of the documentation group.
I'm happy to take up the points raised is #80, but if people are interested in changing the default format for these module description then it shouldn't been done in an adhoc manner, but as a clear change to the Help Text Standards.
Our aim here was to have an consistency that makes it easy for users to use this page.

chipway’s picture

Status: Needs work » Needs review
FileSize
642.55 KB

Thanks for your inputs,

2570985-70.patch didn't apply anymore. I re-rolled it and removed #80, #81.

@xjm, what do you mean by "add a postponed followup for" #80 and #81? I understood create a new issue for them. Am I right?

I think we should create also an issue for #73 (includes block_place and content_moderation).

Do we split new issues and how?

I will add an interdiff later today.

[EDIT] Uploaded wrong file. I see it later.

Status: Needs review » Needs work

The last submitted patch, 84: 2570985-84.patch, failed testing.

chipway’s picture

Status: Needs work » Needs review
FileSize
22.04 KB
3.79 KB
5.5 KB

Correct file for #84: 2570985-70.patch without strings from #80, #81.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

ifrik’s picture

Adding the issue tags again that got removed, and working on this during DevDaysSeville.

ifrik’s picture

Issue summary: View changes

I've changed the issue summary to make this issue for stable modules only. Experimental modules need their own issues because they are too much changing their functionality and if we continue playing catch-up on them we won't be going anywhere.

Chipway, your patch seem to have revert a number of texts back to their original wording, even though they had been reviewed repeatedly. I'm not sure assume that's an oversight in the roll-back. So unless the modules have been mentioned in #80, I revert the wording to what it previously was.
The most of the proposals in #81 are not in accordance to the Help text standard. I'll have a look at the points raised, but I'll stick to the standards.

We can discuss changing them, but then that should be done generally and be documented and not on an ad-hoc basis.

ifrik’s picture

I've fixed the changes that got lost in the re-roll, and took up the comments in #80.
I've changed the "contains" to a wording with "for" for more field types, because it does sound clearer and I really couldn't remember why we previously had come up with that term.