Add README.txt to core

Woo! 278k patch engage!

The last submitted patch failed testing.

This one actually applies >.<

The last submitted patch failed testing.

They pass locally....let's give that another go.

For me, this is Won't Fix or By Design. Should we tell people to eat vegetables and wear their seat belts? Drupal is not your nanny.

Why not just have a README.txt or DEVELOPER.txt with this sort of information?

I consider the patch to make all files carry this banner won't fix. It's going to turn into a maintenance nightmare, and I can pretty much guarantee contrib won't follow suit consistently, so it's rather pointless.

Something like a DEVELOPER.txt is interesting... it could maybe explain an overview of how Drupal works and how it is intended to be extended, including the "Don't hack core" rule? The question is, will people new to Drupal find it, and if not, where?

The last submitted patch failed testing.

Cross-posted. Adjusting title.

To be clear, this should not be covering the material in http://drupal.org/contributors-guide. At all. (Though it should certainly link to it!) This should basically impart over-arching philosophical concepts about how to approach extending Drupal, including:

1. Don't hack core.
2. Drupal has a theme system. Learn it.
3. Drupal has a hook system. Learn it.
4. There's API documentation. Read it.

Basically, the simple things we know that we all take for granted that could save new people literally dozens of hours of headaches doing things totally wrong.

I think it's time for a README.txt - in fact, it amazed me that something that almost all contrib modules have isn't in core!

What's attached is a broad overview of "what's available, where". It doesn't aim to replace INSTALL.txt or UPGRADE.txt. It covers webchick's points, as well as information about contributing and getting involved.

The only thing that's missing is a URL for information about why hacking core is bad. I assumed something existed, but I can't find it.

The last submitted patch failed testing.

DeviantIntegral, see my patch above. It contains the link ~4000 times ;)

Thanks - I've added it to the file. Note that this file is not in patch format as I want it to be easy for anyone to edit, so expect test bot fails. Is there a way to get the bot to not change this issue to needs work?

Weird. I have no idea why the bot would be testing text files. Anyway, moving to the proper component so we can get some docs team eyeballs on this. I'll try pinging the list, too.

This will solve it.

A few comments... Basically, I like the idea and structure of this README, but I am not sure about the exact choice of wording and links in a few places:

a) I don't like "Drupal's power comes from the set of contributed modules and themes available to integrate into your website.".... Don't we think Drupal core is powerful?

I would prefer something that explains what themes and modules do, and also a link to information on how to install them, such as:

You can customize the look of Drupal by installing and enabling a contributed theme. See http://drupal.org/project/themes to find themes, and http://drupal.org/getting-started/5/install-contrib/themes for information on installing them.
You can add features to Drupal by installing and enabling a contributed module. See See http://drupal.org/project/modules to find modules, and http://drupal.org/getting-started/5/install-contrib/modules for information on installing them.

And yes, I think that Drupal 5 installation guide for themes and modules is the most current one we have! Sigh.

b) How about expanding the Do Not Hack Core note to say:

Don't hack Drupal core! See http://drupal.org/node/144376 for information about why you shouldn't hack core. Instead, the best way to modify how the core of Drupal behaves is to install or develop a module. See above for information on installing modules, and http://drupal.org/developing/modules for information on developing modules.

c) API's should be APIs (no apostrophe should be used on an acronym to indicate plural).

d) http://api.drupal.org/api/group/hooks/7 is not a very illuminating doc for new developers. How about linking to ... hmmm... maybe http://drupal.org/node/326 (Working with the Drupal API)?

e) Main place to look for documentation on how to create/modify a theme: http://drupal.org/theme-guide

[And as a note, what sun did in #19 was to attach a blank patch so that the test bot would not keep going back to the previously-submitted latest patch, from #3, which was the one that kept getting tested. The bot doesn't test .txt files.]

I've taken the liberty of making it more concise. Use or toss these edits as you like -- no love lost.

I've taken the liberty of making it more concise. Use or toss these edits as you like -- no love lost.

Re-titling issue. This is about more than developers now (and that's a good thing!)

I don't have a strong opinion about concise (#22) vs. wordy (#17). But most (not all) of my comments in #20 still apply to the concise style of README.

Well, I like the less verbose 22, but to be honest I don't really see a need for this file at all so I'd vote won't fix.

I mean you could just as easily make this file really short as follows...

"Want the best information about how to manage, extend, and theme your drupal installation? Visit the drupal documentation at ..."

I mean if we're not doing something like this at the drupal documentation root page then that's the real problem.

I do see the need for a readme file. I have seen quite a few new Drupal users who didn't know where to start with customizing their Drupal installation. As Lullabot's podcast already points out: in many CMS'es, documentation and customization are all about what to change in which core files. Coming from such an environment, Drupal's hooks are a huge paradigm shift.

Personally, I prefer the concise version from #22. However when I go back to when I started with Drupal: I think I wasn't able to say if I was an administrator, a developer or a themer. I was just a guy who wanted to get things done. That's why I think the document should not describe roles, but tasks - new version attached.

I like the task-oriented headers of #26. Still not sure about concise vs. wordy. Several comments in #20 still apply to the latest patch.

I think this is a great idea for people who are just getting started with Drupal no matter their level of expertise. I've made a few changes to the text for the following reasons:
People who don't understand development/coding (me) are going to look under CHANGE THE APPEARANCE OF YOUR DRUPAL SITE if they want to change the look, go to the 1st link and back right out. So I moved the easy theme link below that title. Same with the coding & modules. I also move the coding portion below the theme as I believe most newbies will stop reading as soon as they see the word code.

I think the changes in #28 are good, but if you change the order of the sections, the order of the headers in the index needs to be changed accordingly.

I like WebWeaver64's updates, it's a lot easier to understand.

I think spending a couple of lines more fully elucidating this point, will be time well spent.

Don't hack Drupal core:
See http://drupal.org/node/144376

Someone that is totally new to Drupal, won't actually know which directories are core and which ones are modifiable, and if they are smart enough to find the readme.txt file, they are smart enough to understand some brief directions.

(oh rats, I'm not feeling smart this morning) Maybe something like this:
-- or maybe this belongs on the Don't hack Core page.

Drupal uses a well thought out system of .... to allow you to customize and extend the functionality of your drupal site, and allow for easy maintenance to facilitate security updates.

Use the sites/all and sites/default folders for modules and themes

So if you are going to link to that page, make sure you have some of the fiddly bits explained.

Some examples:
Core includes most of the directories - except sites - which gets customized, and have a list of files that are basically configurable -- like .htaccess - which often needs to be modified for special applications. Then link to the handbook so they can find more information for themselves.

I'm also of the opinion that shorter is better; since changing README.txt once it's committed will involve patching and CVS, that's one more step for doc team members for updating. I think pointing to pages on d.o is much more sustainable.

The role-based headings from the first file were influenced by the d.o redesign work. IMO new users are most likely to know their own role / skills versus what they want to do, since Drupal has so much terminology to learn.

I also remember the redesign being about how Drupal is a community; regardless of the wording (short like #28 or something else), we should be sure it stays in the doc.

Other then the heading order mentioned in #29, the only addition I can see would be a short sentence or two about what Drupal is at the very top. I'd say we just use what's on the home page:

Drupal is an open source content management platform supporting a variety of websites ranging from personal weblogs to large community-driven websites.

@deviantintegral: there is a big difference between knowing your skills and knowing your own role. I really think that most new users do not know their own role, especially because the words "administrator", "developer" and "themer" are Drupal terminology themselves, much more so than the task based descriptions.

But don't take my word for it - maybe we should just ask our target audience. Tonight I asked one friend of mine who has some experience with CMS site maintenance, but never built a CMS based site herself. She could not answer the question "If you wanted to build a Drupal site, which role would you be?" while showing her the 3 roles. She found it easier to answer the question "If you wanted to build a Drupal site, where would you start?" while showing her the 3 tasks. That said, she found the word 'appearance' too vague in this context - she would rather have seen something like 'change how your site looks'.

(And before anyone mentions it, I realize that asking 1 person is not enough to draw conclusions from.)

Hey marcvangend: Asking 1 person is better than asking no people, or those of us who are "experts" speculating! :)

Indeed - thanks marcvangend.

I've made the following edits:

• Added a short "About Drupal" section with a direct link to drupal.org.
• Fixed the order as mentioned in #29.
• Added a note about sites/all/modules and sites/all/themes to the "don't hack core" note. I agree that it's important as "hacking core" is as much jargon as "killing kittens" is.
• Renamed appearance to "look and feel"
• Added a newline to the end of the file for future diff-ing goodness.

Thanks deviantintegral, the changes look good. I'm attaching a new version with more consistent typography (if you can call it that in a txt file).

The only thing I'm not sure about yet is:

* Don't hack Drupal core:
Place new modules and themes in sites/all/modules and
sites/all/themes.

To me, that is not the essence of 'don't hack core'; it's important to use the sites folder, but what really matters is that you don't alter core files, right?

Ouch, forgot the attachment.

...and here is one more for consistency (just one extra blank line)

I was attempting to match the style in INSTALL.txt. Here's an update which shortens the '-' beneath each heading to be the length of the text.

The version in #38 is pretty close... A few suggestions:

a) In the "look and feel" section, how about adding this link: http://drupal.org/theme-guide -- I think it is a better place to start than http://api.drupal.org/api/group/themeable/7, but at least it should be an additional link.

b) In the "write code" section:

I think this would be better as two separate bullet points:

c) Also in "write code":

Minor suggested change:

d) Add http://drupal.org/node/326 to the links in the API bullet point. Or better yet, combine the current API and hooks bullet points into:

Here is an update implementing all of the suggestions in in #39.

I like #40. Maybe some of the other reviewers should chime in before we mark it RTBC though?

#40 looks good. RTBC AFAIC.

Erm. :) Joining the community has nothing to do with configuring your site. http://drupal.org/handbook/customization seems like an obvious thing to link to here.

Sorry, but we are not linking to anything with "5" in the URL from Drupal 7's README.txt. We should either create the pages in the proper place, or do as api.drupal.org does and make a single URL that always points to the most current data.

Also, I appreciate terseness, but these descriptions feel a bit overly terse. People who already know what they're doing aren't going to bother reading this document. This document is for the person who just downloaded Drupal for the first time and wants to know what's up. And currently, they need to click every single link in here to know if they need to read it or not. (which, of course, they won't.)

An example of going from "super terse" to "reasonably terse" might be changing a section like:

to something like:

The text there I'm sure needs some love, but that's about the level of terseness I was going for. Think "Paragraph overview about whatever to give me the gist, followed by links to external resources with more details, each accompanied with a one-sentence description to help me decide if i should click it."

Sounds like that's a "needs work" from webchick...

Here's an update that:

1. Adds an intro paragraph to each section. The first one is based off of #43. The L&F section notes the distinction between "front end" and "back end" since that was seen as a UX issue from before. The code intro section also reminds users to look for existing modules rather than re-inventing the wheel.
2. Moves a few items out of the "write code" section into the "use and configure", since sites/all/* really is for everyone.
3. Notes languages in the Theme and Code sections, so someone who wants to modify CSS (for example) will hopefully know where to look.
4. Doesn't address the D5 specific pages. I'm willing to go create placeholders at */7 if given the word.

I've attached a diff from #40 as well in case that helps anyone to review.

Just a short brain fart: nobody ever reads readme files. What about a (hook_)help page?

There is some inconsistency in the way links are listed. Some links are prefixed with "See " while others aren't. Is there some kind of logic that I'm unable to see, or should we fix this? I would propose to replace all occurrences of "See http://" with "http://".

I'm generallly positive on the version in #45.

Suggestions for improvement:
- +1 on #47.
- Another style inconsistency: Sometimes bullet points start with "To do xyz" and sometimes they start with "Do xyz". Should pick one style and stick to it.
- "Drupal ships with a base of common functionality such as managing content or user accounts. " => change "or" to "and". Applies to a later sentence as well in that paragraph, and pretty much everywhere else the word "or" is used in the document.
- I am not all that comfortable with the term "ships" in this README, since people are downloading it... How about saying "The core version of Drupal (the version you get when you download Drupal from the drupal.org website) comes with a base..." in the first paragaraph, and then referring to "core Drupal" afterwards? That would introduce people gently to the term "core" as well, and distinguish between core Drupal, Aquia Drupal, etc.
- Add the note about putting core modules/themes in sites/all to the Theme section.

Here's an update which:

1. Replaces See http with http as per #47.
2. Replaces "To do xyz" with "xyz".
3. Replaces most or's with and's.
4. Replaces the "ships with" sentence with "Drupal core (what is included in drupal-7.xx.tar.gz) includes a base of common
   functionality such as managing content and user accounts." I think this is better as it's entirely possible to get Drupal from another source. I'm not sure about replacing all instances of Drupal with "core Drupal"; IMO that's very close to a rebranding of Drupal, which is beyond the scope of this issue.

@jhodgdon: I'm not sure what you mean about your last point; are you suggesting duplicating the note in the Use and Configure section in the Theme section? Or something about moving core themes to sites/all?

Now that #538660: Move update manager upgrade process into new authorize.php file (and make it actually work) is in core, perhaps the stuff about how to install new modules should mention the Update manager and the ability to just visit admin/config/modules/install and paste in a URL to a .tar.gz file to install it in your site? Ditto installing themes at admin/appearance/install. Or, both could just link to admin/reports/updates/install which also works...

I think we're getting close to rtbc, but I agree with Webchick in #43 that we shouldn't be linking to pages that are explicitly D5 documentation.

Instead of http://drupal.org/getting-started/5/install-contrib/themes, there is a better version available at http://drupal.org/node/70151. We could use that link (maybe someone can create a nice path alias for it).

I couldn't find a replacement for http://drupal.org/getting-started/5/install-contrib/themes, but fortunately installing themes hasn't changed that much since Drupal 5. I think it wouldn't be too much work to create an updated version somewhere, but I'm not sure where the best place would be (Getting started? Theme Guide?). I created an issue for adding a new version-independent theme installation page: #614320: Add version-independent instructions for installing contrib themes.

Regarding the version in #49, I am not sure I like " (what is included in drupal-7.xx.tar.gz) "... Maybe it just needs to say "that you downloaded from drupal.org"?

Also, later in that paragraph, it says " contributed modules are available from the Drupal website" -- should we be explicit and say "available on drupal.org"?

And these two lines:

Here's an update that:

1. Documents using the update manager to install modules and themes in each section as per #50.
2. Replaces the module link with node/70151 as per #51. No change to the theme link at the moment as there isn't one available yet.
3. To address #52, installing modules and themes is now split into their appropriate section instead of combining the two.

I've made some suggested changes to the text. Simple language & less text is best imho. Also I've removed all the how to stuff. This is a read me to tell them not to hack core, and where to go if they want to make changes. Or that is what I understood the intent to be. You start with the how to's and there won't be an end to what you should include. This should give anyone wanting it a base line of where to start and where to go if they do want more information.

The attachment in #54 has a few typography issues:

• Needs to be wrapped to 80 characters.
• Has newlines in the middle of filesystem paths.
• Is missing a space after a bullet point.
• Is missing the // $Id $ CVS tag.

As well, it looks like some of the text doesn't reflect the updates made in #53. It would be good if these could be fixed before reviewing the text changes, as the word wrapping especially makes it hard to compare. Additional review on both #53 and #54 would be appreciated.

Yeah, I actually think README.txt should stay over-viewy and resource-pointy, not instruction-manually. Instruction-manually is for the handbook. But there definitely should be a page (or 7) in the handbook that talks about Update Manager, and we should link to it from here. Let's be careful though not to overwhelm people with external resources. We should aim for 3 links (max of 5 or so) per section. We can add additional sections if needed.

Don't have time for a more in-depth review on this atm, sorry.

I talked with webchick, and she suggested pointing to the handbook instead of explicitly documenting sites/all/* and the plugin manager. We actually were linking to the page for modules, but it wasn't clear. The attached update is from #53 as I didn't want to rewrap the text.

• Breaks installing contributed modules into it's own bullet point, just like for themes.
• Standardizes the text for modules and themes to use the same terms (contributed, download, etc)

Note that none of the handbook pages actually document the plugin manager, but they will presumably be updated closer to release.

Anyone have an update as to the D5 URLs?

Here are my comments and the changed document. I hope that this works better, I'm not sure what I'm doing, and don't know how to indicate the differences.

Including the name of the file (what they downloaded) is important for two reasons. It tells them what is considered "core", and doesn't confuse the issue if they downloaded a bunch of files from drupal.org.

Adding the blurb about enabling core modules is important as they may not realize that not everything is enabled, and they may not need to download anything else just enable something to get the installation to do what they want.

The "learn More" neatly explains that this document isn't telling them the "whole story"

Telling them where to install the additions is important as they may not do this otherwise.

Again indicating that there is more in core then what they are currently seeing I think is important for someone who has no idea what they are getting.

Review notes:

• Please upload files with Unix line endings, not DOS line endings.
• As for creating diff's, see http://drupal.org/patch/create. You don't have to if you don't want to, but it is a valuable skill.
• About file names versus "from drupal.org": File names are great for novices, but it doesn't cover CVS checkouts. I think that if you can do a CVS checkout, you know enough to map that to a file name, so I agree with this change.
• There are some broken newlines in #58:
  -Drupal core (what you downloaded from drupal.org) includes a base of common
-functionality such as managing content and user accounts. Additional features
-are added to Drupal through the use of "modules". Drupal ships with several
+Drupal core (drupal-X.XX.tar.gz) includes a everything you need to get started
+including several "modules" for common functionality
+such as managing content and user accounts. Additional features
• As well, there should always be a blank newline at the end of the file for future patches.
• Why did
  + *Best practices install additions to core in sites/all/ e.g.:
+   sites/all/modules
+   sites/all/themes
  come back?
• What's the purpose of this addition?
  + * Change the default themes with those provided in core.
  * Download contributed themes for Drupal:
• "More contributed modules (not core) are available from the drupal.org to enable additional functionality." is missing the word "website", and I think "not core" is clearer as "separate from core" or "not included with Drupal core".

# Please upload files with Unix line endings, not DOS line endings.
# As for creating diff's, see http://drupal.org/patch/create. You don't have to if you don't want to, but it is a valuable skill.
# About file names versus "from drupal.org": File names are great for novices, but it doesn't cover CVS checkouts. I think that if you can do a CVS checkout, you know enough to map that to a file name, so I agree with this change.

If I understood how to do either I'd be happy to. I'm really just trying to participate and share my thoughts. I intend to learn more about CVS, however at this point I have enough trying to learn how to get my drupal site up.

I tried using a different program to create the .txt file, it didn't seem to help.

Why did
+ *Best practices install additions to core in sites/all/ e.g.:
+ sites/all/modules
+ sites/all/themes
come back?

As I said in my post. I think that this is important to have in there somewhere/somehow as this may be the only thing they read in the beginning before installing modules/themes. I removed all the how to, just included the statement.

What's the purpose of this addition?
+ * Change the default themes with those provided in core.
* Download contributed themes for Drupal:

I believe that it's important for someone new to understand that there is more to core, then what they originally see, and they may not be aware there are any other themes included in core.

I can't get the .txt to wrap or have the correct line breaks so I'm just pasting it here:

// $Id $

CONTENTS OF THIS FILE
---------------------

* About Drupal
* Use and configure your Drupal site
* Change the look and feel of your Drupal site
* Write code for your Drupal site

ABOUT DRUPAL
------------

Drupal is an open source content management platform supporting a variety of websites ranging from personal weblogs to large community-driven websites. For more information, see the Drupal website at http://drupal.org/, and join the Drupal community at http://drupal.org/contribute.

USE AND CONFIGURE YOUR DRUPAL SITE
----------------------------------

Drupal core (drupal-X.XX.tar.gz) includes a everything you need to get started including several "modules" for common functionality such as managing content and user accounts. Additional features are added to Drupal through the use of "modules". Drupal ships with several modules to provide additional functionality such as image uploading, search,
and content translation. More contributed modules (not part of Drupal core) are available from the drupal.org to enable additional functionality.

* Install, upgrade, and maintain Drupal:
See INSTALL.txt and UPGRADE.txt in the same directory as this document.
* Enable additional modules included with core.
* Learn, create and improve your Drupal site:
http://drupal.org/getting-started
* Download contributed modules to extend Drupal's functionality:
http://drupal.org/project/modules
* Install new contributed modules:
http://drupal.org/node/70151
* Move beyond the basics of Drupal:
http://drupal.org/handbook/customization
*Best practices install additions to core in sites/all/ e.g.:
sites/all/modules
sites/all/themes

CHANGE THE LOOK AND FEEL OF YOUR DRUPAL SITE
--------------------------------------------

Drupal contains a theme system to separate the look and feel of a website from its functionality and content. By default, Drupal uses the "Garland" theme for displaying content to users, and uses the "Seven" theme for the administrative interface. To customize Drupal's display further, see the following resources.

* Change the default themes with those provided in core.
* Download contributed themes for Drupal:
http://drupal.org/project/themes
* Install new contributed themes:
http://drupal.org/getting-started/5/install-contrib/themes
* Change Drupal's appearance and output ("theme") with HTML, CSS, and PHP:
http://drupal.org/theme-guide
* Collaborate with other Drupal themers:
http://drupal.org/contribute/themes

WRITE CODE FOR YOUR DRUPAL SITE
-------------------------------

Drupal contains an extensive API to allow the creation of new modules to extend Drupal's core functionality. Nearly any part of Drupal's functionality can be modified and overridden by additional modules by implementing Drupal "hooks".
There are thousands of contributed modules available on the Drupal website.
Before writing a new module, be sure to search the Drupal website for a module which meets your requirements.

* Don't modify core Drupal files ("hack core"):
http://drupal.org/node/144376
* Write modules for Drupal using PHP:
http://drupal.org/getting-started/5/install-contrib/modules
http://drupal.org/developing/modules
* Use Drupal's API and hooks:
http://api.drupal.org/
http://drupal.org/node/326
http://api.drupal.org/api/group/hooks/7
* Contribute to the community by helping build Drupal itself:
http://drupal.org/contribute/development

@WebWeaver64: It sounds like you could use a hand setting up an editor. You might get some help on IRC in #drupal-support; feel free to ping me, and if I'm around I'll try and help you out :)

Also, I think webchick preferred not documenting sites/all* explicitly due to the complexity of explaining the plugin manager and so on, which is why I removed it. More feedback from other doc team members would be useful.

I'm fine not documenting the plugin manager in here. If all goes well, people will just find that in the UI, not by a .txt file that they're unlikely to see/read in the first place. ;)

That said, I think the readme *should* explain where to put the code to extend your site, especially since it's so non-obvious from looking at a drupal directory tree, at least until #22336: Core Drupal in its own directory, configuration, modules and themes in custom is done...

Here is a version fixing only typography issues from #60; I'll post a review of the content in the moment.

This is based off of a comparison of the version from #57:

• The "X" in the version number should be lower case, just like the -dev versions of modules.
• I think saying that core includes "everything you need" is leading new users down the wrong path. Even for D7, most sites will need contrib modules.
• This still needs to be addressed from #59: "More contributed modules (not core) are available from the drupal.org to enable additional functionality." is missing the word "website", and I think "not core" is clearer as "separate from core" or "not included with Drupal core".
• "Enable additional modules included with core." doesn't make any sense on it's own; what's the suggested action?
• I think "Learn, create and improve your Drupal site:" is clearer as "Learn about Drupal to create and improve your site:"
• "Best practices install additions to core in" isn't clear. I think we should follow the format of the version in #53 and have two separate points, one for modules and one for themes, each in the appropriate section.

• "Change the default themes with those provided in core." - this doesn't have an action item. We either need to say "Change your site theme by browsing to Administer > Appearance" or remove this. IMO since we have no other text that is bound to a UI, we shouldn't include this.

I think saying that core includes "everything you need" is leading new users down the wrong path. Even for D7, most sites will need contrib modules.

How about "what you need" removing the word everything but leaving the idea that they can build with what they have. I sometimes think adding all the additional modules in the beginning just leads to more confusion, as you have no idea what is what or what you're doing.

"Enable additional modules included with core." doesn't make any sense on it's own; what's the suggested action?
and
"Change the default themes with those provided in core." - this doesn't have an action item. We either need to say "Change your site theme by browsing to Administer > Appearance" or remove this. IMO since we have no other text that is bound to a UI, we shouldn't include this.

How about:
Enable additional modules included with core.
http://drupal.org/handbook/modules
and
Change the default themes with those provided in core.
http://drupal.org/getting-started/6/admin/build/themes

"Best practices install additions to core in" isn't clear. I think we should follow the format of the version in #53 and have two separate points, one for modules and one for themes, each in the appropriate section.

How about:
Install additions to core in sites/all/ (i.e. sites/all/modules, sites/all/themes)
http://drupal.org/getting-started/5/install-contrib

All of these links are for previous versions and will have to be adapted for D7.

All the other suggestions I agree with.

Here's an update with all of the changes from #64 and #65. Anyone subscribed to this issue with information about what pages should be created for D7, please chime in so we can fix up those URLs!

Looks good to me. Not sure what you're asking us to do as far as the pages that need updating. I believe that most of them need to be updated.

removed version specific # in two urls per request of jhodghon

Thanks! LeeHunter reorganized the installation instructions for contrib modules so they are now part of the installation guide, and sepeck realiased them.

The current URLs for the installation instructions:
http://drupal.org/getting-started/install-contrib
http://drupal.org/getting-started/install-contrib/modules
http://drupal.org/getting-started/install-contrib/themes

Great - only this URL remains linking to a non-D7 page: http://drupal.org/getting-started/6/admin/build/themes

I've attached an update with the URL's and removing a duplicate bullet point.

Looking good, here's a patch rolled with the #70 version.

No discussion for a few days now, but it has been well discussed and edited, so, marking as RTBC?

We're still waiting on a D7 equivalent for the documentation for http://drupal.org/getting-started/6/admin/build/themes.

Re #73: Do we need just a stub, or do we need the whole section to be built?

I don't think we're ready to build the entire page yet, but here's a stub page on Drupal themes:
http://drupal.org/node/637480

Someone with URL alias permissions could make a URL alias. I suggest
site-building/themes

And by the way, I suggest revising the patch slightly. It currently says:

How about:

There is also still one more bad link in the README patch #71, in the bottom section:
http://drupal.org/getting-started/5/install-contrib/modules

That should be:
http://drupal.org/getting-started/install-contrib/modules

It would make sense to add a link to the trademark policy at the footer of the README.txt file (see #637922: Add trademark policy to distribution).

How about the license too?

Here is a patch which:

• Fixes the http://drupal.org/getting-started/6/admin/build/themes and http://drupal.org/getting-started/5/install-contrib/modules links.
• Adds a note about the license and trademark policies. The license sentence is taken from what Firefox uses in their first-run text ("Know your rights"). The trademark policy is linked to http://drupal.com/trademark.

Oh no. http://drupal.org/handbook/modules is in the Archive now, so we'll have to figure out a new link for that one.

http://drupal.org/getting-started is also going away. The handbook is being restructured -- new structure is here: http://drupal.org/handbooks

Sigh.

Probably that whole first section of the Readme needs a careful reexamination. Where's LeeHunter?

I just sent LeeHunter a message asking if he could comment here on better links/organization for the top section of the Readme.

I don't have plans, myself, to make any more major changes to the structure since I've pretty much fixed the things that were driving me crazy for years.

There are still tons of minor fixes to be done though and someone else could easily come along and change things back to the way they were before or make other major changes.

If I was writing the readme I'd cut it right back to three links (with absolutely minimal text):

- licensing
- trademark
- doc landing page

Otherwise we're adding maintenance overhead (cherrypicked links that have to be maintained and discussed) without adding clear value beyond what's already available on the doc landing page. In fact, since the readme is out of sync with the current IA approach on the doc landing page (and possibly with an entirely different future IA when drupal.org gets reorged), it could be a new source of confusion.

Hm. While I see Lee's point, I really think that a three-link, minimal text README.txt would be pointless, really. We have LICENSE.txt to talk about legal stuff, and the handbook is pointed to from literally every help page in core. This doesn't help people to understand the "framework" of Drupal, and pointing them to /handbook certainly isn't going to help with that, either.

Could we instead radically pare down the number of "jump-off" links in each section to just the rock-solid areas of the handbook that are unlikely to change? Or, if that doesn't apply to anything anymore, remove them altogether and just include a section at the beginning that says "for more information on any of these items, see the Drupal.org documentation at /url/?"

How do we tell what areas are "rock solid"? Unlikely means that some time over the course of the D7 cycle links will break. Could we have redirects set up for links included with core which will always point to the appropriate page?

See #644104: Enable path_redirect so core can link to stable documentation URLs about enabling path_redirect on drupal.org so we can link to stable URLs from core.