Create summaries for topics in the User Guide

Oh, I should mention that there are examples of what is needed in the "guidelines" directory in the project (the contributor guidelines book), because I recently edited the main guidelines.txt file for the chapters (which is like the guide.txt file for the main User Guide), as well as the individual topic files, to have summaries.

One other note: I have just learned that the Summary lines must be no more than 140 characters long, for Drupal.org purposes. I will need to update 3 of the ones I made for the Contributor guide.

I realized I need to provide a bit more information on how the summaries will be used.

So, basically, on drupal.org, the plan is to import the User Guide (and guidelines pages too) into the new structure for Documentation pages. In this structure, there is a content type called "Guide", which is basically a table of contents page, and another one called a "Page", which is where you put information.

The Index page for the user guide, as well as the chapter pages, will become "guides". These pages display the titles and summaries of the pages and guides they contain. So, each topic in the user guide and each chapter needs to have a 140-character summary.

I have already imported the Contributor Guidelines book (with the summaries I wrote) into a dev site for drupal.org. Here is what it looks like:
https://guide-drupal.dev.devdrupal.org/documentation/user_guide_contribu...
(htaccess login: drupal/drupal as usual on dev sites)
Then if you click through to a chapter, you get something like this:
https://guide-drupal.dev.devdrupal.org/documentation/user_guide_contribu...

That will give you an idea of what the summaries might look like.

So, let's look at an example from the User Guide itself. How about chapter 7 (managing user accounts) as an example?

We might have the following summaries:
- chapter: Overview of user account concepts and details of common user account tasks.
- user-concept topic: Overview of user accounts, permissions, and roles.
- user-new-role topic: How to create a new role.
...

So... I think we need to adopt a common format for the summaries. I propose:
- Task topics: Start with "How to [verb]..."
- Concept topics: Start with "Overview of..."
- Chapters: "Overview of [....] concepts and details of [....] tasks"
hm... or maybe "Overview of concepts and details of tasks related to [....]".

How does that sound?

Of course, there is only so much information we can put into 140 characters! That is a limitation of the design of the new Documentation Guide and Documentation Page content types on drupal.org -- the summary has that character limit.

Also, if you want to make an initial patch for just part of the summaries, instead of waiting until you've written all of them, that would be fine! :)

This looks great!

1. +++ b/source/en/guide.txt
   @@ -112,6 +133,9 @@ include::user-content.txt[]
   +Overview of block concepts and details of custom block tasks.
   

   I think I would take out the word 'custom' here, because it also covers how to place blocks (which may not be "custom" blocks). Replace with "common".

2. +++ b/source/en/guide.txt
   @@ -130,6 +157,9 @@ include::views-block.txt[]
   +Overview of multilingual site concepts and details on common translation tasks.
   

   The tasks here are not just translation, also setting up the site to be multilingual... maybe

   ...details of tasks needed to make a site multilingual.

So I made these two small changes and committed this patch.

As a note: we need summaries added for the Preface and Appendix too if possible. They look at little bare at the moment on the dev site where I'm testing out the imports. ;)

Thanks! It looks like the patch in #17 includes the patch in #16, so I just reviewed that one.

This looks mostly wonderful! A few small notes:

1. +++ b/source/en/block-regions.txt
   @@ -2,6 +2,9 @@
   +Overview of regions present in a theme.
   

   It's more of an overview of what regions are, in the context of themes?

2. +++ b/source/en/content-create.txt
   @@ -2,6 +2,9 @@
   +How to creating a content item for use as the home page.
   

   needs copy edit. (creating -> create)

3. +++ b/source/en/content-edit.txt
   @@ -1,6 +1,9 @@
   +How to edit a content item to update data on the home page.
   

   I think we shouldn't mention the home page specifically. The topic should be applicable to editing *any* content item.

   I'm not sure about "update data" either?

4. +++ b/source/en/menu-concept.txt
   @@ -2,6 +2,9 @@
   +Overview of menus and its different types.
   

   needs copy edit (its -> their).

   I'm not sure about "its different types" either?

   So it's an overview of the concept of menus, and also what menus are automatically created with the Standard install profile.

5. +++ b/source/en/menu-home.txt
   @@ -2,6 +2,9 @@
   +How to configure a content item so that it gets displayed as the home page.
   

   Very nice! :)

6. +++ b/source/en/planning-modular.txt
   @@ -1,6 +1,9 @@
   +Overview of modular content and how content in a page is sourced from other content items.
   

   is -> can be
   (maybe?)

7. +++ b/source/en/planning-structure.txt
   @@ -1,6 +1,9 @@
   +How to plan a content structure that decides which content entity type to use for content on the website.
   

   When I read this, I felt like it was saying that there was only 1 content entity type that would be used for all content. Maybe needs a slight rewording?

8. +++ b/source/en/structure-content-display.txt
   @@ -2,6 +2,9 @@
   +How to make content items more end user-friendly.
   

   Hm. I think I would talk about good presentation rather than user-friendliness.

9. +++ b/source/en/structure-form-editing.txt
   @@ -2,6 +2,9 @@
   +How to change a form to use a different widget.
   

   Hm. I am not sure about this one.

   For one thing, it is only about the forms used to edit content.

   For another thing, there are other changes you can make besides just changing widgets (like hiding some fields, and changing the order).

10. +++ b/source/en/structure-image-style-create.txt
    @@ -2,6 +2,9 @@
    +How to add an image style to display variations of an image on a page.
    

    This sounds like I'm displaying multiple variations of the same image on the same page?

    Maybe:

    ... to reformat an image
    ... to resize or otherwise alter an image

    or something like that? We can probably lose "on a page" too.

11. +++ b/source/en/structure-reference-fields.txt
    @@ -2,6 +2,9 @@
    +Overview of reference fields and its commonly used types.
    

    needs copy edit (its -> their)

12. +++ b/source/en/structure-taxonomy-setup.txt
    @@ -2,6 +2,9 @@
    +How to create a vocabulary and add terms to it.
    

    maybe "taxonomy vocabulary" would be clearer here? Also besides creating a vocabulary, this topic also covers adding it as a field to a content type.

13. +++ b/source/en/structure-taxonomy.txt
    @@ -2,6 +2,9 @@
    +Overview of taxonomy and how it can be used to categorize posts in a website.
    

    Let's not use the word "post" here. "content" is preferred.

14. +++ b/source/en/structure-text-format-config.txt
    @@ -2,6 +2,9 @@
    +How to make a change to the Basic HTML text format and its editor configuration.
    

    let's not be specific about "basic HTML". The steps could be used for any text format.

15. +++ b/source/en/structure-view-modes.txt
    @@ -2,6 +2,9 @@
    +Overview of view mode and field formatter.
    

    The other summaries used plurals, so should this be "view modes and field formatters"?

16. +++ b/source/en/structure-widgets.txt
    @@ -2,6 +2,9 @@
    +Overview of forms and widgets
    

    end in .

17. +++ b/source/en/understanding-data.txt
    @@ -1,6 +1,9 @@
    +Overview of common types of data featured on a site.
    

    featured? Maybe "used" would be better, or "making up" or something like that?

18. +++ b/source/en/understanding-distributions.txt
    @@ -2,6 +2,9 @@
    +Overview of distributions and its different types to set up use-specific websites.
    

    needs copy edit (its -> their)

19. +++ b/source/en/understanding-gpl.txt
    @@ -2,6 +2,9 @@
    +Overview of Drupal licensing and the guidelines to be followed by contributors.
    

    Not only contributors, but people who use the software, or modify it for their own purposes, need to follow and understand the license.

20. +++ b/source/en/understanding-project.txt
    @@ -2,6 +2,9 @@
    +Overview of FOSS, Drupal project, and Drupal Association.
    

    Let's not use acronyms in summaries without explaining them.

21. +++ b/source/en/understanding-themes.txt
    @@ -2,6 +2,9 @@
    +Overview of themes and how to start working with them.
    

    well it doesn't really tell you how to do anything. Maybe:

    Overview of themes and where to obtain them.

This is great! Nearly perfect! I fixed a few very very very minor things:
- planning-structure - missing newline after the [role="summary"] line
- structure-text-format-config - some edits from your last patch were reverted. Put those back in.
- structure-widgets - misplaced .

Committed! Thanks!

I think this patch covered a bit over half of the guide, so setting the issue back to "Active" to get the rest done. Great work so far!

@jojyja - do you still plan to make summaries for the rest of the topics? This is a higher priority than the copy editing right now, if you have time... Thanks!

Thanks for the next batch! These look pretty good. I have a few suggestions:

1. +++ b/source/en/language-add.txt
   @@ -2,6 +2,9 @@
   +How to add a language to a site.
   

   This topic also covers which modules you need to install, and turning on the language switcher block, so maybe we should include that in the summary?

2. +++ b/source/en/language-concept.txt
   @@ -2,6 +2,9 @@
   +Overview of translatable content on a site.
   

   One of the main points of this topic is that it's not just content that is translatable ("content" has a particular meaning in the context of Drupal), and the topic covers how to translate content, configuration, and UI text.

   Given that... how about:

   Overview of translation on a site.

3. +++ b/source/en/language-config-translate.txt
   @@ -1,6 +1,9 @@
   +How to translate labels on a page.
   

   Well it's not just labels, and not all labels are configuration, so it doesn't cover how to translate all labels.

   So... how about something like:

   How to translate field labels in a view, and other configuration.

4. +++ b/source/en/user-admin-account.txt
   @@ -2,6 +2,9 @@
   +Overview of the User 1 account.
   

   Maybe:

   Overview of the User 1 account, also known as the root account or administrative account.

5. +++ b/source/en/user-content.txt
   @@ -1,7 +1,10 @@
   +How to assign content items to a user account.
   

   how about "...assign authorship of content items..."

6. +++ b/source/en/views-parts.txt
   @@ -2,6 +2,9 @@
   +Overview of a view's sections.
   

   I don't think I would call them "sections"... Maybe "the administrative parts of a view" or "what you can edit in a view" or something like that?

Wow, three patches, thanks!

The patch in #28 looks great, committed.

The other two look pretty good, but I think need a few updates before committing:

Review of batch 4, comment #29:

1. +++ b/source/en/extend-maintenance.txt
   @@ -2,6 +2,9 @@
   +How to enable maintenance mode to allow access only to authorized users, and how to disable it.
   

   Maintenance mode, besides denying access, also puts up a message saying the site is undergoing maintenance. I think that is probably more appropriate to say than "denying access".

2. +++ b/source/en/prevent-cache-clear.txt
   @@ -2,6 +2,9 @@
   +How to clear a cache using Drush or the user interface.
   

   I think I would say "the cache" rather than "a cache"?

3. +++ b/source/en/prevent-cache.txt
   @@ -2,6 +2,9 @@
   +Overview of cache and the site data that can be cached.
   

   ... of the cache ... ?

Review of batch 5, comment #30:

1. +++ b/source/en/attributions.txt
   @@ -1,6 +1,9 @@
   +The list of contributors to this guide, from launch to completion.
   

   That is what the page *used* to contain. But now it just has information about some of the contributors. We recently moved the individual topic authors and editors to the topic files, so this file just has information about project management and people like you who did guide-wide editing and writing tasks.

2. +++ b/source/en/copyright.txt
   @@ -1,6 +1,9 @@
   +Understanding the copyright perspective of this guide, and how users can make use of the content featured herein.
   

   I am not sure about "copyright perspective".

   How about just:

   Copyright information for this guide.

3. +++ b/source/en/glossary.txt
   @@ -1,6 +1,9 @@
   +[role="summary"]
   +An alphabetical list of definitions for terms used in this guide.
   +
   

   I don't actually think we can put a summary in the Glossary file. I may have told you we needed one, but ... glossaries have a very specific special format in AsciiDoc, and every time I've tried to add something to this file, it has broken the build. So, let's just leave it without a summary.

4. +++ b/source/en/guide.txt
   @@ -230,6 +234,8 @@ include::glossary.txt[]
   +[role="summary"]
   +Overview of terms used in this guide and the chapters they can be found in.
   

   I think we'd better leave this out too. Indexes are also special.

5. +++ b/source/en/security-cron.txt
   @@ -2,6 +2,10 @@
   +[role="summary"]
   +
   +How to run cron maintenance tasks using the core Automated Cron module, or by running them from outside the site.
   

   Extra blank line in middle here.

6. +++ b/source/en/thoughts-learn-more.txt
   @@ -1,6 +1,9 @@
   +Where to find additional material to gain advanced Drupal skills.
   

   Let's leave the word "Drupal" out, as we do throughout the guide.

   Maybe "advanced site-building skills" would be good?

The patch in #5 had a couple of small glitches, which I fixed (like the cron summary getting into the cache topic, whoops!). Anyway, thanks! These look great. Committed. I think this issue is done but will need to verify by building/importing the site again, later today. Marking fixed; will reopen if necessary.

I imported this into the new dev site (a preview of how it will, hopefully very soon, look on Drupal.org)... looks great! See
https://guide-drupal.dev.devdrupal.org/docs/user_guide/en/index.html
(access: drupal/drupal as usual) The landing page shows the chapter summaries. Then click through to a chapter to see individual topic summaries.

I looked through all of the chapters, and the summaries are excellent -- thanks @jojyja!! I made a few very minor updates.

Anyway, this is looking very good! One step closer to having this live on drupal.org....