Update the module descriptions on the Extend page

patch has been re-submitted and is running.

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.

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.

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?

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.

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!!

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.

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.

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!

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.

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

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.

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

Hopefully @Bojhan can comment/review...

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

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.

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.

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

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.

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

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.

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.

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?

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.

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?

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

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

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

Little update including #67.

@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

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.

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.

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.

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.

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.

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!

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.

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

I think this warrants discussion with @yoroy, we need to get this in one go and stop iterating :)

Reviewed the patch.

I like the clear language and consistency in word choice and punctuation.
As far as I can see, language-wise, this looks good (unless there are style guidelines we're adhering to and that I'm missing).

Overall I think these are great improvements, just some minor questions / comments.

1. +++ 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 (containing content, forms, etc) and to place them in the regions of a theme.'
   

   I just learned that "etc" needs a dot like "etc.". Thank you @xjm

2. +++ b/core/modules/block_content/block_content.info.yml
   @@ -1,6 +1,6 @@
   -description: 'Allows the creation of custom blocks through the user interface.'
   +description: 'Allows the creation of custom blocks and block types.'
   

   This one feels overly specific. Do users really need to know about block types here?

3. +++ 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 would suggest something like "Provides the capabilities to add new fields to entities."

4. +++ b/core/modules/field_ui/field_ui.info.yml
   @@ -1,6 +1,6 @@
    type: module
   -description: 'User interface for the Field API.'
   +description: 'Provides a user interface for managing fields.'
    package: Core
   

   It feels like the field UI and the field module could be more similar. How about "Provides a user interface for field module?"

5. +++ b/core/modules/simpletest/simpletest.info.yml
   @@ -1,6 +1,6 @@
   -description: 'Provides a framework for unit and functional testing.'
   +description: 'Provides a framework for running automated tests.'
   

   I think this should be more like "Provides an interface for running automated tests."

About comment 2: I think it is important to say that the Block Content module also includes the creation of custom block types, because otherwise it is unclear which of the two block modules provide that functionality.
I've taken up the rest of the comments.

Good point!

I went through the entire list of descriptions and they seem to follow the standard defined in the issue summary. They all seem to be reasonable for me, so it feels like getting things in would make sense.
Given these are string changes, we would just apply this to 8.7.x I assume.

I think this one is tricky to review, because it isn't just a straight "reformat this description to fit the standards"; in many cases it's "re-write the string with a different meaning entirely" and it's not completely clear why we're doing that.

For example:

-description: 'Enables banning of IP addresses.'
+description: 'Allows users to ban visits from specific IP addresses.'

The old description seems to follow the standard just fine ("The description starts with a verb and should be short and concise."). But now we've introduced the concept of users banning visits from specific IP addresses, but this is incorrect. Administrators may be able to do that, with proper permissions, but regular users, no.

And then in an example like this:

-description: "WYSIWYG editing for rich text fields using CKEditor."
+description: 'Provides a visual text editor (WYSIWYG) and adds a toolbar to text fields using CKEditor.'

Here we're switching a non-verb to a verb, which is good (adheres to the first part of the rule: "The description starts with a verb"), but we're also vastly extending the description, which goes against the second half of the rule: "should be short and concise." We have help pages for extended info; these descriptions should basically be only the minimal amount of information for someone to determine whether or not they should turn it on or off.

I think we should try and re-scope this to just reformatting any texts that don't follow the standard. For example:

-description: "WYSIWYG editing for rich text fields using CKEditor."
+description: 'Provides a WYSIWYG editor for rich text fields using CKEditor.'

...as this we could get in quickly.

And then, maybe have another meta issue to talk about whether the existing standard allows enough information, and maybe adjust it in response, and at that point, add back in some of these more creative ones.

It will be much easier to review this issue if we are much more detailed in the "Proposed Resolution" section of the issue summary. As is, I have to examine the patch or study the comments to see what changes are being recommended.

For the same reason, let's copy the appropriate section of the page on Help text standards. Keep the link to the full page.

I think that updating the issue summary qualifies as a Novice task.

Closed #2999585: Update the Datetime Range module description in favour of this issue. Crediting people who worked on that issue - wla_g, ifrik, wengerk, Gábor Hojtsy

Tagging for upcoming contribution days.

Marked #3045382: RESTful Module Description: add dot to the end of the sentence as a duplicate and crediting the patch author @RuslanP

Marked #3045379: Unify sentence closings of core module description lines on Extend page as a duplicate. Crediting @Balu Ertl and @RuslanP for working on that one.

Patch rerolled

@vacho Thanks for rerolling the patch, which now I tested, applies cleanly:

@webchick's review from #113 has not been addressed. I think the key point that we should :

try and re-scope this to just reformatting any texts that don't follow the standard. For example:

-description: "WYSIWYG editing for rich text fields using CKEditor."
+description: 'Provides a WYSIWYG editor for rich text fields using CKEditor.'

...as this we could get in quickly.

And then we can open an issue to refine the standard and make the other improvements this issue suggests.

@ifrik thanks! I don't think we should have individual issues. I think we should have 1 issue for the simple type of formatting / rules as @webchick documents and 1 for the more complex improvements that need a bit more discussion.

Tagging for DrupalNorth 2019

I have reviewed the patch created in #136 as per my understanding

name: Actions
type: module
-description: 'Perform tasks on specific events triggered within the system.'
+description: 'Allows configuration of tasks that will be executed in response to events.'

Rather we can use 'Allows configuration of tasks to be executed in response to events' that will shorten the sentence as well as will improve the sentence build

name: Aggregator
type: module
-description: 'Aggregates syndicated content (RSS, RDF, and Atom feeds) from external sources.'
+description: 'Gathers and displays syndicated content (RSS, RDF, and Atom feeds) from external sources.'

Aggregated better describe the sentence then gathers as the module name is also aggregator. For display we can rather put Aggregate and display syndicated contents (RSS, RDF and Atom Feeds) from external sources.

name: Breakpoint
type: module
-description: 'Manage breakpoints and breakpoint groups for responsive designs.'
+description: 'Manages breakpoints and breakpoint groups for responsive designs.'

Use of tense is not correct. Either it should be 'manage breakpoints and breakpoint groups' or 'manages breakpoint and breakpoint group'

name: Comment
type: module
-description: 'Allows users to comment on and discuss published content.'
+description: 'Allows users to comment on content.'

It should be 'allow users to comment on the published content.
name: Image
type: module
-description: 'Defines an image field type and provides image manipulation tools.'
+description: 'Defines a field type for image files and provides tools to configure their display.'

Instead we can use Defines a field type for image media and provides display configuring tools

-name: Internal Page Cache
+name: 'Internal Page Cache'
type: module
-description: 'Caches pages for anonymous users. Use when an external page cache is not available.'
+description: 'Caches pages for anonymous users and can be used when external page cache is not available.'

Rather we can use 'Caches pages for anonymous users to use when external page cache is not available.'

This is all what i found can be changed. I might be wrong as well.
Thanks

Tagging for badcamp2019

The patch is not applying on my system

I was successfully able to apply the patch in #139 on Drupal core 8.9.x. @cheng75, try cloning Drupal core from the project page instructions on 8.9.x or 9.0.x branch.

1. +++ b/core/modules/aggregator/aggregator.info.yml
   @@ -1,6 +1,6 @@
   -description: 'Aggregates syndicated content (RSS, RDF, and Atom feeds) from external sources.'
   +description: 'Aggregate and display syndicated contents (RSS, RDF and Atom Feeds) from external sources.'
   

   This should be "Aggregates and displays".

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

   There is a regression here with the tense. Should be "Allows users"

3. +++ b/core/modules/aggregator/aggregator.info.yml
   @@ -1,6 +1,6 @@
   -description: 'Aggregates syndicated content (RSS, RDF, and Atom feeds) from external sources.'
   +description: 'Aggregate and display syndicated contents (RSS, RDF and Atom Feeds) from external sources.'
   

   This should be "Aggregates and displays".

I reviewed the patch and the issue. I think this is still a Novice issue for fixing the language in the patch.

Hii

I have created patch as per suggestions in #144.

the patch is not applying

Is it applying for you guys ?

Now tested, I do confirm that latest patch attached to comment #148 does cleanly applies to the current HEAD of 8.9.x branch (at commit hash 25fd25a).

Read through the suggested changes and I agree that they convey message better based on the viewpoints discussed above. So I take the bravery to mark es RTBC. I hope we can get them into core soon, so leave enough time for translator colleagues as well, to have the chance to re-translate such important strings until June.

Committed 915b74f and pushed to 9.0.x. Thanks!
Committed 5b786ae and pushed to 8.9.x. Thanks!

I cherry-picked this forward to 9.0.x because the patch won't apply to 9.0.x but git could sort it out :)

These descriptions are certainly better than what we have now and more consistent. There might well be future updates and improvements but trying to do them on this issue is only going to stop people from getting these improvements - let's not let perfect be the enemy of the good (or something like that).

Yay! 🙌 🎊🍻