Make the text in modules, themes, and profiles README.txt files more user-friendly

Related: https://drupal.org/node/604342

• Use a neutral and polite tone.
• Keep the purpose of sites in mind when writing text for the UI: most sites are used in a professional environment - so use appropriate wording.
• Use active writing and make sure it is clear who performs a certain action. Do not use the pronoun "we." For example, do not write text like "we delete these files" (who deletes them?). If something works automatically (and the user should know about it, write (e.g.) "Temporary files are deleted automatically by the system. " If the user should take a particular action, the text should instruct the user directly: "Delete unnecessary files."
• Do not use 'Please'. This makes it sound as if the user is supposed to do a favor for someone.
• Do not use 'Sorry', e.g., in error messages.
• Avoid emotional verbs and adjectives. E.g., it should be normal that an admin can install a module, so there is no "success" in it. If the installation fails, the admin gets an error message.
• Do not use contractions like e.g., 'You've, Can't, Shouldn't. Use the complete phrase instead such as 'You have, Cannot, Should not'
• Refer to other parts of the website using single quotes, e.g., "Indexing behavior can be adjusted using the 'Search settings' page" ( (where 'Search settings' should be a link).

So... The current text is active voice. It says "Place ... here". That is active, and is a direction for what the reader should be doing. The proposed text of "This directory should be used ..." is passive. So I don't think that is exactly the right direction to go in for an update.

But, sure, we could split the sentence up into two sentences, and make it more user-friendly, as long as we follow the guidelines in #1 (thanks for putting those there, that is indeed what should be followed).

Some other things to consider:
- We do not actually want this version's README files to refer to previous versions' ways of doing things. They just need to document what the current way of doing things is, and (if appropriate) briefly why. If we refer to old versions, it just gets confusing, and hard to maintain.
- Friendly is nice, but not if it gets in the way of finding the information people need. So we don't want a whole lot of "Welcome" text, but a friendly tone is OK.
- WordPress has a completely different approach to its UI and "feel" than Drupal, so I wouldn't take what it does as a suggestion for this project necessarily. For instance, WordPress used to use a lot of jargon like "Howdy!" -- I don't know if they still do, but I don't think we want that. We would prefer to use language that is clear and readable to international folks, possibly with low levels of English, deaf people, and English speakers from countries other than the US, in all of our README files and other documentation. Also, we have a standard about not using "Please" (as you see above in #1), and other standards that are adopted from best practices in the technical documentation community.
- The README files in /modules and /themes are *not* the main README file for Drupal 8. The main README is at the top level / directory. README files in sub-directories should not get wordy, and should be specific to the particular sub-directory functionality.

Anyway, please do make a patch -- that would be the best way to communicate the specific changes you think should be made, rather than making general suggestions (which is nice, but doesn't necessarily lead to action being taken). Thanks!

That is a great suggestion... In the last sentence: ensure -> ensures... And yes I think we do want to say that an additional module that you would put there extends Drupal core functionality. Thanks!

This would be a good novice task for Global Sprint Weekend. Updated the issue summary with the latest suggestion.

Please review attached patch.

We could of saved this issue for a novice...

+++ b/modules/README.txt
@@ -1,7 +1,6 @@
+from the Drupal community may be downloaded at http://drupal.org/project/modules.

This goes over the 80 character width limit.

ahh, I missed that. Good caught thanks.

Sorry by mistake posting this patch,otherwise RTBC.

Sorry,didn't saw your updated patch earlier so posted mine patch.
Since you have rectified your only mistake in previous patch so RTBC.
Thanks.

On further reflection, I am not really completely happy with the latest patches. I don't think that merely putting modules in the right place really "ensures safer core updates". They aren't made "safer" by this and it doesn't "ensure" anything.

Can we rewrite that last sentence somehow?

Also the download page on d.o is now at https://www.drupal.org/project/project_module rather than http://drupal.org/project/modules. The latter redirects to the new location, but probably better to show the new URL in the README and avoid the redirect.

Hi there :-)
I have re-written the first paragraph. Keeping in mind, I first started using Drupal three days ago, and am a novice, I would hope this paragraph is easy to understand for Drupal newcomers. Speaking a second language myself, I have tried my best to minimise complex language / grammar structures, for the benefit of people whose native language is not English.

The patch file is attached, but for simplicity so you can just take a read of it, I will paste my paragraph below too:

Use this directory to add extra or customized modules to your Drupal installation. Adding modules can extend the functionality of Drupal's core. Modules contributed from the Drupal community can be downloaded from https://www.drupal.org/project/project_module. Storing additional modules here ensures Drupal's core can be updated safely, without damaging any modules.

Thanks!

A few things to fix:

a) We need similar updates to the README files in the top-level themes and profiles directory.

b) "Drupal's core" should be referred to as "Drupal core".

c) I am not sure about the word "damaging". Can we maybe use "affecting"? Or the wording in #16.

d) It's a bit "choppy" (sentences are short and not connected together with connection words), and also it seems to jump from "put stuff here because" to "here's what modules are and how to find them" and back to "put stuff here because". So... it just doesn't read well... maybe the some of it can be moved to another paragraph? There are already 3 more paragraphs in this file, and the next one is about "where to put stuff"...

So.

Here is what I think we should do:

- Start with a simple explanation of what modules are, like "Modules extend Drupal core functionality."

- The rest of the first paragraph can explain that you should put them in this directory and why.

- Then keep the existing 2nd paragraph about subdirectories, and existing 3rd paragraph about multisite.

- Then add the part about downloading to the last paragraph, which is also talking about custom development.

Does that make sense? The main point of this README is to explain what you should put in this otherwise empty directory, so let's make sure that information is emphasized. The stuff about where to find modules is covered in the top-level README already.

@jhodgdon - Thanks for your thoughts. I will do some more work on it...

@jhodgdon, thanks for giving such a comprehensive review, I completely agree with all your points, in particular that the purpose of this README file is to explain and emphasise the reason for / use of this directory.

The basic outline of the modules/README.txt file should be something like:

• what modules are / what they do, and where / why to put them here
• using subdirectories
• use in a multisite configuration
• where to get modules, and where to get more information.

Using a similar structure, where appropriate, would probably also be a good idea for the top-level themes and profiles directories README files you mentioned.

In this revision of the file I have changed:
-- "Drupal's core" to "Drupal core"
-- "damaging" to "affecting" (Have further adjusted this tricky sentence. Am still open to suggestions)
-- the structure, re-ordering the points into the structure outlined above.

The patch and interdiff are attached, but I will paste the README text below too.

Adding extra or customized modules to your Drupal installation can extend the functionality of Drupal core, allowing your Drupal system to gain many new capabilities. Use this directory to add modules to your Drupal installation. Storing additional modules here ensures Drupal core can be updated safely, without affecting any of the modules in this directory.

It is safe to organize modules into subdirectories, such as "contrib" for contributed modules, and "custom" for custom modules. Note that if you move a module to a subdirectory after it has been enabled, you may need to clear the Drupal cache so that it can be found.

In multisite configuration, modules found in this directory are available to all sites. In addition to this directory, shared common modules may also be kept in the sites/all/modules directory and will take precedence over modules in this directory. Alternatively, the sites/your_site_name/modules directory pattern may be used to restrict modules to a specific site instance.

Modules contributed from the Drupal community can be downloaded from https://www.drupal.org/project/project_module. Refer to the "Developing for Drupal" section of the README.txt in the Drupal root directory for further information on extending Drupal with custom modules.

Hi Andy, maybe we could rephrase a little more?

Use this directory to add custom/contrib modules to enhance your site. Storing custom/contrib modules here away from core, facilitates clean upgrade of core without affecting custom/contrib modules.

Custom/contrib modules can be placed in separate subdirectories. Clear Drupal Cache to re-enable a module if it has been moved within directories after enabling.

In multisite configuration, modules in this directory are available to all sites. Additionally, shared common modules may also be kept in the sites/all/modules directory, which will take precedence over modules in this directory. sites/your_site_name/modules directory pattern may be used to restrict modules to a specific site instance.

It is put very nicely, quite clear. There are just a few minor things I'd like to point out.

In the first paragraph, on line #5, for a more grammatically correct expression I think it would be written "ensures that Drupal core", instead of just "ensures Drupal core".

In the third paragraph, word "multisite" needs to be written as "multi-site", according to Drupal documentation. But, maybe it would be better it is written: "If you are using the multi-site feature, modules found in this directory will be available to all sites."
I'd prefer "feature" than "configuration", because it is a feature.
The next sentence may be a bit more simple and clear without the first part: "Shared common modules may be also kept in the sites/all/modules directory and will take precedence over modules in this directory."

In the fourth paragraph, the meaning of the sentence would be that the modules have somehow contributed from the Drupal community, which is not the case, but it needs to be said that the modules were contributed by the community. So, my suggestion is: "Modules contributed by the Drupal community..."

Download and applied patch to local instance of Drupal 8. Read the revised text, much easier to read and new instructions/suggestions are more helpful.

There is also an open issue related to this for Drupal 7 that I had forgotten about (which I just marked as related to this one):
#1539940: Encourage best practices in /sites/README.txt, /modules/README.txt, /profiles/README.txt and /themes/README.txt

Also fixing the title to be more English. ;}

Regarding the latest patch:

a) ", allowing your Drupal system to gain many new capabilities." Let's get rid of this. Unnecessary given the first part of the sentence.

b) Agree with the review in #22 regarding "ensures that".

c) Disagree with the review in #22 regarding "multisite". See core/INSTALL.txt where we use "multisite" all over the place. Let's at least keep the README files consistent, and if we're going to change one we need to change all of them. "multisite configuration" is also used in INSTALL.txt. So let's keep the 3rd paragraph how it is now.

d) Agree with the comment in #22 regarding the 4th paragraph.

e) Agree with #21 that the wording in the patch is better than the wording suggested in #20.

Thanks!

@jhodgdon

Thanks for the review!

Agree with the comment. But what about the thing that multisite is a feature, not configuration, maybe just that word needs to be changed?

Identifying this as a potential good issue for Sprint Weekend. See discussion at #2407325: preparing for a sprint, would be good to have a list of candidate issues. Adding sprint queue tag.
If this is worked on during the sprint, please add the tag SprintWeekend2015. Add a comment when you start work saying what you are about to do, so we can coordinate.

We use the phrase "multisite configuration" in the INSTALL.txt file. Let's also use it here.

Removed tag by mistake.

In the third paragraph what does it mean by "will take precedence over.."? Does it mean that in cases of the same module existing on the multisite and local levels the configuration at the local level is used? If so, shouldn't we say so? If not, what does it mean?

In addition to this directory, shared common modules may also be kept in the sites/all/modules directory and will take precedence over modules in this directory.

It is safe to organize modules into subdirectories...

What do people think about clarifying this? What do you mean by safe (is it going to crash my computer if I don't put the files here)? How about...

Place downloaded and custom modules in this directory. This ensures these modules remain separate from Drupal Core’s modules. This allows Drupal Core to be updated without affecting the configuration of your added modules.

I am new to readme files, but would it help clarification to add section headings? Something like below?:

--Modules are…

Modules extend your site functionality beyond Drupal Core.

--Place in this directory…

Place downloaded and custom modules in this directory. This ensures these modules remain separate from Drupal Core’s modules. This allows Drupal Core to be updated without affecting the configuration of your added modules.

--Download additional modules…

Contributed modules from the Drupal Community may be downloaded at http://drupal.org/project/mdules.

--Organizing modules in this directory…

You may create subdirectories in this directory, to organize your added modules, without breaking the site. Some common subdirectories include “Contrib” for contributed modules, and “custom” for custom modules. Note that if you move a module to a subdirectory, after it has been enabled, you may need to clear the Drupal cache so it can be found.

--Multisites and this directory…

In multisite configuration, modules found in this directory are available to all sites. In addition to this directory, shared common modules may also be kept in the sites/all/modules directory and will take precedence over modules in this directory. Alternatively, the sites/your_site_name/modules directory pattern may be used to restrict modules to a specific site instance.

--More information…

Refer to the “Developing for Drupal” section of the README.txt in Drupal root directory for further information on extending Drupal with custom modules.

Is this discussion for all readme.txt files? If so I have a suggestion for the main readme.txt file: http://cgit.drupalcode.org/drupal/tree/README.txt

Under "Developing for Drupal" spell out the acronym API (Application Programming Interface), the first time it is used.

RE #35: This discussion is about the modules/ themes/ and profiles/ README files... and I disagree about spelling out API. I think people are more familiar with the acronym, in this case, than the full name. Anyway please file a separate issue if you want to discuss further.

RE #34, looks pretty good!

The "place in" paragraph has a lot of "This" in it, can that be fixed? Also I don't think this sentence makes any sense at all:

This allows Drupal Core to be updated without affecting the configuration of your added modules.

It is not the *configuration* that would be affected. It's the files.

Also " Some common subdirectories include “Contrib” for contributed modules, " "contrib" should be lower-case. And in the patch, please do not use "smart quotes".

Anyway... we need a patch! Thanks!

#36 RE #35 - okay, I had to look it up but a basic Google search for API does get a good definition (as long as you ignore the result for the American Petroleum Institute ;)

#36 RE #34

Place downloaded and custom modules in this directory. This ensures these modules remain separate from Drupal Core’s modules which allows Drupal Core to be updated without overwriting these files.

Better?

#36 I will use lower case on contrib and will remove the smart quotes (really dumb question: what does that mean?)

It will take me a few days to create a patch. I've never done it before and have to find the time to look it up.

The Themes file is similar, should I create a patch that ads subheadings to that one as well?

I like the new text! You need a comma before "which" however.

What I mean by smart quotes is the slanty quotes in “custom” , as opposed to the ASCII quote character in "custom"

And yes, the patch needs to fix the modules, themes, and profiles README files, all in a similar manner. All the changes should go into the same patch file.

Thanks!

You may be interested in the Core Contribution mentoring office hours, if you are new to making a patch:
https://www.drupal.org/core-mentoring
Or if you cannot make it to IRC during those hours, here's documentation:
https://www.drupal.org/novice

Here is a patch for all three README files, all that seemed necessary was some grammar changes.

Regarding the patchin #39, a necessary comma was lost here:

diff --git a/profiles/README.txt b/profiles/README.txt
index 69bb492..b76df7f 100644
--- a/profiles/README.txt
+++ b/profiles/README.txt
@@ -2,7 +2,7 @@ Place downloaded and custom installation profiles in this directory to ensure

-In multisite configuration, installation profiles found in this directory are
+In multisite configurations installation profiles found in this directory are

Also, we seem to have lost all the previous work. Let's get that back. :(

@jhodgdon,

I have use #34 as a template for themes, and profile README.txt. In addition, I have added the #36, #37, #38, #39 suggestion in just one patch.

Here is the results:

modules/README.txt

--Modules are…

Modules extend your site functionality beyond Drupal Core.

--Place in this directory…

Place downloaded and custom modules in this directory. This ensures these
modules remain separate from Drupal Core’s modules which allows Drupal Core
to be updated without overwriting these files.

--Download additional modules…

Contributed modules from the Drupal Community may be downloaded at
http://drupal.org/project/mdules.

--Organizing modules in this directory…

You may create subdirectories in this directory, to organize your added
modules, without breaking the site. Some common subdirectories include
"custom" for contributed modules, and "custom" for custom modules. Note that
if you move a module to a subdirectory, after it has been enabled, you may need
to clear the Drupal cache so it can be found.

--Multisites and this directory…

In multisite configurations, modules found in this directory are available to
all sites. In addition to this directory, shared common modules may also be
kept in the sites/all/modules directory and will take precedence over modules
in this directory. Alternatively, the sites/your_site_name/modules directory
pattern may be used to restrict modules to a specific site instance.

--More information…

Refer to the “Developing for Drupal” section of the README.txt in Drupal root
directory for further information on extending Drupal with custom modules.

themes/README.txt

--Themes are…

Themes allow you to change the look and feel of your Drupal site. You can use
themes contributed by others or create your own.

--Place in this directory…

Place downloaded and custom themes in this directory to ensures these
themes remain separate from Drupal Core’s themes which allows Drupal Core to
be updated without overwriting these files.

--Sub-theme

It is safe to organize themes into subdirectories and is recommended to use
Drupal's sub-theme functionality to ensure easy maintenance and upgrades.
For more information about sub-themes https://www.drupal.org/node/225125

--Download additional themes..

Contributed profiles from the Drupal Community may be downloaded at
https://www.drupal.org/project/project_theme

--Multisites and this directory…

In multisite configurations, themes found in this directory are available to
all sites. In addition to this directory, shared common themes may also be kept
in the sites/all/themes directory and will take precedence over themes in this
directory. Alternatively, the sites/your_site_name/themes directory pattern may
be used to restrict themes to a specific site instance.

--More information…

Refer to the "Appearance" section of the README.txt in Drupal root
directory for further information on extending Drupal with custom themes.

profiles/README.txt

--Profiles are…

Installation profiles define additional steps that run after the base
installation provided by core when Drupal is first installed. There are two
basic installation profiles provided with Drupal core.

--Place in this directory…

Place downloaded and custom installation profile in this directory to ensures
these installation profile remain separate from Drupal Core’s installation
profile which allows Drupal Core to be updated without overwriting these files.

--Download contribute profiles…

Contributed profiles from the Drupal Community may be downloaded at
https://www.drupal.org/project/project_distribution

--Multisites and this directory…

In multisite configurations, installation profiles found in this directory are
available to all sites during their initial site installation. Shared common
profiles may also be kept in the sites/all/profiles directory and will take
precedence over profiles in this directory. Alternatively, the
sites/your_site_name/profiles directory pattern may be used to restrict a
profile's availability to a specific site instance.

--More information…

Refer to the "Installation profiles" section of the README.txt in Drupal root
directory for further information on extending Drupal with custom profiles.

Thanks... but these files do not seem similar to the other README files we have in Core, in how they are creating headers. We generally use ALL CAPS not things like --Modules are… to make headers.

Also they contain the non-ASCII ... character, and the headers should not end in ... anyway. So for instance, instead of "Modules are...", a better header would be something like "What is a module". Or really we don't need a header there at the top of the file.

And there is no newline at the end of some of the files.

So... Please look at the other .txt files in the core directory and make these files conform to their formatting.

I would be working on this then.

Thanks! Also for the next time... just post the patch, don't repost what you did in the issue comment, we can look at the patch file.

Updated patch with the modification base on the comment #42.

OK, this is looking better, thanks!

A few nitpicks and suggestions and typos -- and most of these apply to all three files, although I have only mentioned them in one file:

1. +++ b/modules/README.txt
   @@ -1,18 +1,38 @@
   +PLACE IN THIS DIRECTORY
   

   Maybe this should be "What to place in this directory"? (in all caps)

2. +++ b/modules/README.txt
   @@ -1,18 +1,38 @@
   +modules remain separate from Drupal Core’s modules which allows Drupal Core
   

   Need comma before which. Also please use the ASCII ' character, not the extended ’ character for the apostrophe.

3. +++ b/modules/README.txt
   @@ -1,18 +1,38 @@
   +http://drupal.org/project/mdules.
   

   typo in URL

   Should be:

   https://www.drupal.org/project/project_module

4. +++ b/modules/README.txt
   @@ -1,18 +1,38 @@
   +modules, without breaking the site. Some common subdirectories include
   +"custom" for contributed modules, and "custom" for custom modules. Note that
   +if you move a module to a subdirectory, after it has been enabled, you may need
   

   typo: should be "contrib" for contributed modules. Whoops.

5. +++ b/modules/README.txt
   @@ -1,18 +1,38 @@
   +MULTISITES AND THIS DIRECTORY
   

   How about making this header just "Multisite Configuration" ?

6. +++ b/modules/README.txt
   @@ -1,18 +1,38 @@
   +all sites. In addition to this directory, shared common modules may also be
   +kept in the sites/all/modules directory and will take precedence over modules
   +in this directory. Alternatively, the sites/your_site_name/modules directory
   +pattern may be used to restrict modules to a specific site instance.
   +
   

   This seems a bit awkward to me, the part about which ones take precedence.

   Maybe change this sentence to:

   You may also put modules in the sites/all/modules directory, and the versions in sites/all/modules will take precedence over versions of the same module that are here.

7. +++ b/profiles/README.txt
   @@ -1,18 +1,32 @@
   +Place downloaded and custom installation profile in this directory to ensures
   +these installation profile remain separate from Drupal Core’s installation
   +profile which allows Drupal Core to be updated without overwriting these files.
   

   typos:
   profile -> profiles
   ensures -> ensure
   and then in the next line:
   profile -> profiles

   and in the last line, need a comma before "which". Or maybe make this two sentences? It's kind of run-on.

8. +++ b/profiles/README.txt
   @@ -1,18 +1,32 @@
   +DOWNLOAD CONTRIBUTE PROFILES
   

   typo: contributed

9. +++ b/themes/README.txt
   @@ -1,16 +1,38 @@
   +Contributed profiles from the Drupal Community may be downloaded at
   

   typo: should be themes not profiles for this file.

10. +++ b/themes/README.txt
    @@ -1,16 +1,38 @@
    +Refer to the "Appearance" section of the README.txt in Drupal root
    

    ... in *the* Drupal root directory ...

Here is an updated patch.

fixing status

Better, but several of my review points from #47 were not addressed. See for example #2, #3, #4 ... I stopped reviewing at that point. Please check again.

Better, thanks! Still a few minor things to fix:

1. +++ b/modules/README.txt
   @@ -1,18 +1,37 @@
   +Contributed modules from the Drupal Community may be downloaded at
   

   Community should be lower-case. Applies to other README files as well.

2. +++ b/modules/README.txt
   @@ -1,18 +1,37 @@
   +"custom" for contrib modules, and "custom" for custom modules. Note that
   

   first custom => contrib

3. +++ b/modules/README.txt
   @@ -1,18 +1,37 @@
   +Refer to the “Developing for Drupal” section of the README.txt in Drupal root
   

   "in Drupal root" => "in the Drupal root"

4. +++ b/profiles/README.txt
   @@ -1,18 +1,32 @@
   +installation provided by core when Drupal is first installed. There are two
   

   Elsewhere we've called "core" "Drupal core" in these README files. Let's be consistent.

5. +++ b/profiles/README.txt
   @@ -1,18 +1,32 @@
   +basic installation profiles provided with Drupal core.
   

   Also let's get the capitalization consistent. Check other README files to see whether it should be "Drupal Core" or "Drupal core". I am not sure which one we normally do.

6. +++ b/profiles/README.txt
   @@ -1,18 +1,32 @@
   +Place downloaded and custom installation profiles in this directory to ensures
   

   ensures => ensure

7. +++ b/profiles/README.txt
   @@ -1,18 +1,32 @@
   +these installation profiles remain separate from Drupal Core's. Installation
   +profiles which allows Drupal Core to be updated without overwriting these files.
   +
   

   This sentence is garbled.

8. +++ b/profiles/README.txt
   @@ -1,18 +1,32 @@
    available to all sites during their initial site installation. Shared common
    profiles may also be kept in the sites/all/profiles directory and will take
    precedence over profiles in this directory. Alternatively, the
    sites/your_site_name/profiles directory pattern may be used to restrict a
    profile's availability to a specific site instance.
    
   

   Is this actually true that you can use sites/all/profiles and sites/*/profiles? I am not sure it is accurate. It was not possible to do in 7.

9. +++ b/themes/README.txt
   @@ -1,16 +1,37 @@
   +Place downloaded and custom themes in this directory to ensures these
   

   ensures => ensure

10. +++ b/themes/README.txt
    @@ -1,16 +1,37 @@
    +themes remain separate from Drupal Core's themes which allows Drupal Core to
    

    comma needed before which

I'm at the DrupalCon sprint and am working on this.

5. The README.txt have core lower case, for this reason I have change all my "Drupal Core" to "Drupal core"
7. Yes, it sounds kinda confusing. I remove it but I think we should add more content on the "WHAT TO PLACE IN THIS DIRECTORY?"
8. I'm sure that is wrong I did not notice. That was my mistake carry over for the "original" text.

I updated modules/README.TXT, profiles/README.TXT and themes/README.TXT per suggestions by jhodgdon. I made no change in response to her "Is this actually true that you can use sites/all/profiles and sites/*/profiles? I am not sure it is accurate." since I also don't know whether it is accurate.

darol100 uploaded a patch between the time I started working on this and the time I uploaded mine (yeah, I'm a novice). See interdiff.txt

Some notes.

1. I missed "Drupal Community" to "Drupal community" in two of the three README.TXT files (profiles/README.txt and themes/README.txt).

2. darol100 chose "Drupal core" over "Drupal Core" based on the root README.TXT. I chose based on a readme I based on what I found in "core/lib/README.TXT".

3. I made th WHAT TO PLACE IN THIS DIRECTORY section of profiles/README.txt consistent with the other two readme files in the patch (as opposed to darol100 who removed garbled text).

4. I did not change the MULTISITE CONFIGURATION section of profiles/README.txt per jhodgdon comment # 8.

5. I missed the "Drupal root" to "the Drupal root" change in the MORE INFORMATION section of profiles/README.txt.

6. I made the WHAT TO PLACE IN THIS DIRECTORY section of themes/README.TXT consistent with the corresponding sections of the other two readme files.

I'm testing this at DrupalCon right now, and making some text changes.

@jemandy,

No problem, thank you so much for the interdiff.txt. We are working on fixing this issue at the room 403. Next time, you should consider assigned to yourself. If you are working on a issues assigned to yourself. Just like I did and rhuffstedtler.

Feel free to join us.

+++ b/profiles/README.txt
@@ -18,10 +21,13 @@ MULTISITE CONFIGURATION
-profiles may also be kept in the /profiles directory.
+profiles may also be kept in the sites/all/profiles directory and will take
+precedence over profiles in this directory. Alternatively, the
+sites/your_site_name/profiles directory pattern may be used to restrict a
+profile's availability to a specific site instance.

Didn't take the change to lines 25-28 because this is incorrect.

Updated capitalization and quotes.

I'm with @darol100 and @rhuffstedtler reviewing the latest changes by #64. These changes were based on #58 and #59.

I'm unassigning per the protocol today at DrupalCon.

+++ b/profiles/README.txt
@@ -1,18 +1,30 @@
+MULTISITE CONFIGURATION

@rhuffstedtler opened up an issue at https://www.drupal.org/node/2489526 to discuss the usage of multisite vs multi-site as we both think the inconsistent spelling of the term may lead to confusion.

Despite the comment I made above, I believe this patch is ready to be applied.

+++ b/modules/README.txt
@@ -1,18 +1,37 @@
+modules, without breaking the site. Some common subdirectories include
+"contrib" for contrib modules, and "custom" for custom modules. Note that
+if you move a module to a subdirectory, after it has been enabled, you may need

+++ b/profiles/README.txt
@@ -1,18 +1,30 @@
+profiles may also be kept in the /profiles directory.
...
+----------------

It appears we do not usually use the opening slash to indicate the Drupal root: "profiles" v. "/profiles". Omitting the slash has at least one advantage: the Drupal root may not always be the website doc root. What should our policy be?

+++ b/themes/README.txt
@@ -1,16 +1,37 @@
+Place downloaded and custom themes in this directory to ensures these

Change "directory to ensures" to "directory. This ensures" to make more consistent with other readme files and correct the grammar.

I should have changed the status at Comment #69.

This patch fixes the subject verb agreement problem in themes/README.txt

+++ b/themes/README.txt
@@ -4,7 +4,7 @@ themes contributed by others or create your own.
 be updated without overwriting these files.

What about this wording? "Placing downloaded and custom themes in this directory separates custom themes from Drupal core's themes. This allows Drupal core to be updated without overwriting these files." I think the voice is less passive and is more straightforward.

@abenamer - That seems like reasonable wording to me.

@rhuffstedtler, created a patch based on his previous patch. This needs to be just in one patch. I would work on merging everything.

+++ b/themes/README.txt
@@ -4,9 +4,9 @@ themes contributed by others or create your own.
+Placing downloaded and custom themes in this directory separates custom themes
+from Drupal core's themes. This allows Drupal core to be updated without
+overwriting these files.

I have added the same text to the modules/README.txt but I replace themes with modules for consistency. I have attached a new patch with all @rhuffstedtler patches.

1. +++ b/modules/README.txt
   @@ -1,18 +1,37 @@
   +from Drupal core's modules. This allows Drupal core to be updated without ¶
   

   Trailing whitespace.

2. +++ b/profiles/README.txt
   @@ -1,18 +1,30 @@
   +installation provided by Drupal core when Drupal is first installed. There are two
   

   80 character limit.

Updated patch base on #76.

Tested and it looks good to me.

@iwant2fly,

So this should be RTBC ? If so, can you change it to RTBC.

Looks very good to me. That said I do see one slight oversight.
in /modules/README.txt, under MultiSite, there is no mention of /sites/your_site_name/modules. Fix that and I'd say it is RTBC

A few more things to fix... some of these have been in previous reviews, sigh. Really it's easier to deal with an issue if one person starts working on it and keeps going until the end, rather than different people making patches... oh well! Thanks everyone for your contributions anyway!

1. +++ b/modules/README.txt
   @@ -1,18 +1,37 @@
   +Placing downloaded and custom modules in this directory separates custom modules
   +from Drupal core's modules. This allows Drupal core to be updated without
   +overwriting these files.
   +
   

   This says "downloaded and custom" at the beginning, then says it just separates "custom" modules from Drupal core. This is confusing. Second use should say "these modules" or "downloaded and custom" I think.

2. +++ b/modules/README.txt
   @@ -1,18 +1,37 @@
   +Contributed modules from the Drupal community may be downloaded at
   +https://www.drupal.org/project/project_module.
   +
   

   In the first section these are called "downloaded". I think we should be consistent: always call them "contributed".

3. +++ b/modules/README.txt
   @@ -1,18 +1,37 @@
   +"contrib" for contrib modules, and "custom" for custom modules. Note that
   

   "for contrib modules" -> "for contributed modules".

4. +++ b/modules/README.txt
   @@ -1,18 +1,37 @@
   +if you move a module to a subdirectory, after it has been enabled, you may need
   

   remove comma before "after".

5. +++ b/profiles/README.txt
   @@ -1,18 +1,30 @@
   +profiles may also be kept in the /profiles directory.
   

   Um, this is confusing. This readme is in the /profiles directory. So this doesn't make any sense?

6. +++ b/themes/README.txt
   @@ -1,16 +1,37 @@
   +Placing downloaded and custom themes in this directory separates custom themes
   

   Same comment as with the Modules readme about "downloaded and custom" vs. just "custom".

   Also downloaded -> contributed as in the modules README.

7. +++ b/themes/README.txt
   @@ -1,16 +1,37 @@
   +SUB-THEME
   +---------
    
    It is safe to organize themes into subdirectories and is recommended to use
    Drupal's sub-theme functionality to ensure easy maintenance and upgrades.
   +For more information about sub-themes https://www.drupal.org/node/225125
   +
   

   I don't see how the organization into subdirectories is related to subthemes? Make a seaparate section or put the note about subdirectories into the "What to place in" section?

8. +++ b/themes/README.txt
   @@ -1,16 +1,37 @@
   +For more information about sub-themes https://www.drupal.org/node/225125
   

   This sentence no verb

Updated patch base on #80 and #81.

Getting better, thanks! Still a few things to fix.

1. +++ b/modules/README.txt
   @@ -1,18 +1,38 @@
   +Contributed modules from the Drupal community may be contributed at
   

   may be contributed -> may be downloaded

2. +++ b/profiles/README.txt
   @@ -1,18 +1,29 @@
   +Place downloaded and custom installation profiles in this directory.
   +Installation profiles are generally provided as part of a Drupal
   +distribution. They only impact the installation of your site. They do not
   +have any effect on an already running site.
   +
   

   This should be wrapped better, so it comes closer to 80 character lines.

3. +++ b/profiles/README.txt
   @@ -1,18 +1,29 @@
   +DOWNLOAD DISTRIBUTIONS
   +----------------------------
   +
   +Contributed profiles from the Drupal community may be downloaded at
   +https://www.drupal.org/project/project_distribution
   +
   

   The Themes and Modules files say "Additional" in the header for this section. Let's make them all consistent.

   Also, you cannot download *profiles*, you will be downloading a distribution, right?

4. +++ b/themes/README.txt
   @@ -1,16 +1,32 @@
   +functionality to ensure easy maintenance and upgrades. For more information
   +about how to create sub-themes https://www.drupal.org/node/225125
   +
   

   Still a sentence without a verb. Should say:

   ... create subthemes, see https://www.....

5. +++ b/themes/README.txt
   @@ -1,16 +1,32 @@
   +Contributed themes from the Drupal community may be contributed at
   

   may be contributed -> may be downloaded

6. +++ b/themes/README.txt
   @@ -1,16 +1,32 @@
   +directory for further information on extending Drupal with custom themes.
   

   I'm not sure if we usually refer to theming as part of 'extending'. It's not part of the Extend main menu item in the Drupal UI, and in the Appearance section of the main README it does not use the word "extend" either. So maybe we should say "... for further information on customizing the appearance of Drupal" or something like that?

Updated patch base on #84

Great, almost there! Still one or two problems, which (sorry!) I may have missed in previous reviews.

1. +++ b/profiles/README.txt
   @@ -1,18 +1,29 @@
   +installation provided by Drupal core when Drupal is first installed. There are
   +two basic installation profiles provided with Drupal core.
   +
   

   Just realized we should probably take out this "There are two basic ..." sentence. We aren't doing this for other READMEs, and actually there are more than just those two provided by Core (there are currently 6, though 4 are for testing).

2. +++ b/profiles/README.txt
   @@ -1,18 +1,29 @@
   +Contributed distributions from the Drupal community may be downloaded at
   +https://www.drupal.org/project/project_distribution
   +
   

   In the Modules readme, this sentence ends with . but not here. Let's make sure they're consistent.

3. +++ b/themes/README.txt
   @@ -1,16 +1,33 @@
   +about how to create sub-themes, see https://www.drupal.org/node/225125
   

   Oops, just noticed this is the Drupal 7 subtheme page.

   Actually does this information about subthemes really belong in here anyway? Should be in the main README in the section about developing themes, if at all. It is not really related to this directory.

4. +++ b/themes/README.txt
   @@ -1,16 +1,33 @@
   +Refer to the "Appearance" section of the README.txt in the Drupal root directory
   +for further information on customizing the appearance of Drupal with custom
   +themes.
   -- 
   

   Yeah, see, this is where we direct people to more information about themeing. Let's leave it at that for this file.

Updated patch base on #86.

Thanks for the new patch! We're finally almost there, but not everything was really done:

+++ b/themes/README.txt
@@ -1,16 +1,32 @@
+without overwriting these files. It is recommended to use Drupal's sub-theme
+functionality to ensure easy maintenance and upgrades.
+

Once again, can we take out this sentence about the sub-theme functionality? It is not relevant to this README.

I have remove that sentence about sub-themes.

Thanks everyone for all the patches! I think this is finally ready to go!

Looks like this needs a reroll.

I would take care of this...

Here is an update version of the patch with the latest Drupal core.

Thanks for the reroll -- looks good!

These are great docs changes. Committed 3f56e7f and pushed to 8.0.x. Thanks!

Some work on backporting this is at #1539940-116: Encourage best practices in /sites/README.txt, /modules/README.txt, /profiles/README.txt and /themes/README.txt (and nearby comments) - just needs to be moved over here :)

The only two comments related to back-porting in this issue #1539940: Encourage best practices in /sites/README.txt, /modules/README.txt, /profiles/README.txt and /themes/README.txt are #116 and #117. Just in case you are trying to contribute, I do not want you to read 120 comments.

First time attempt--thank you novice tag. This patch updates the README.txt in both sites/all/modules and sites/all/themes with the new version as well as creates a README.txt file for profiles with its new text.

Looks pretty good! A few small things to fix:

1. +++ b/sites/all/modules/README.txt
   @@ -1,17 +1,39 @@
   +In multisite configurations, modules found in this directory are available to
   +all sites. You may also put modules in the sites/all/modules directory, and the
   +versions in sites/all/modules will take precedence over versions of the same
   +module that are here. Alternatively, the sites/your_site_name/modules directory
   +pattern may be used to restrict modules to a specific site instance.
    
   

   Um... This *is* the sites/all/modules directory. :) So the text needs a bit of adjustment here for Drupal 7.

2. +++ b/sites/all/modules/README.txt
   @@ -1,17 +1,39 @@
   +Refer to the “Developing for Drupal” section of the README.txt in the Drupal
   

   Did we have these "smart quotes" in the 8.x version of the README? I hope not. [Yes, we did, sigh.] Please use ASCII quotes instead. We'll need a new issue to fix the 8.x README in the top-level modules directory too.

3. +++ b/sites/all/themes/README.txt
   @@ -1,14 +1,31 @@
   +In multisite configurations, themes found in this directory are available to
   +all sites. You may also put themes in the sites/all/themes directory, and the
   +versions in sites/all/themes will take precedence over versions of the same
   

   See note above about sites/all/modules.

4. +++ b/sites/all/themes/README.txt
   @@ -1,14 +1,31 @@
   \ No newline at end of file
   

   Whoops.

Woo, I learned how to do interdiff files. I removed the extra lines about sites/all/modules and sites/all/themes. I don't think we need any more information there, but let me know if we do. I fixed the quotation marks--I believe it was just that one set. And all files have a newline at the end.

Looks great, thanks!

One more small thing:

+++ b/sites/all/modules/README.txt
@@ -1,17 +1,36 @@
-Drupal cache so that it can be found. (Alternatively, you can disable the
-module before moving it and then re-enable it after the move.)
+Drupal cache so it can be found.

Maybe we should leave this text about disable/re-enable? It doesn't work for Drupal 8, but is applicable to 7.

I absolutely agree. I remember reading that line after I setup a contrib directory, moved all my modules into it, and everything broke.

Thanks!

+++ b/sites/all/modules/README.txt
@@ -1,17 +1,37 @@
+Drupal cache so it can be found. (Alternatively, you can disable the
 module before moving it and then re-enable it after the move.)
 

Looks good... line should be rewrapped so "module" is up on the previous line though. We try to get as close to 80 characters as possible.

That makes sense. I'll add that to my list of things to check.

Looks good, thanks!

Committed to 7.x - thanks!