Lullabot's most recent podcast inspired this issue. Patch to follow.

The basic concept is that there would be a commented message at the top of all Drupal files saying "Don't hack this file" and pointing them to a relevant node on d.o that explains why not.

CommentFileSizeAuthor
#204 607028-204.patch3.71 KBmarcvangend
#202 607028.202-README.patch3.61 KBdeviantintegral
#201 607028.201-README.patch3.61 KBdeviantintegral
#200 607028-198.patch3.71 KBmokko
#199 drupal_607028-198.patch3.71 KBEvanDonovan
#193 607028-193.patch3.71 KBmokko
#184 607028-184.patch3.71 KBmarcvangend
#182 607028-182.patch3.67 KBjhodgdon
#176 607028-176.patch3.84 KBjhodgdon
#172 607028-172.patch3.18 KBjhodgdon
#171 interdiff.168-171.txt1.83 KBmokko
#171 607028.171.README.patch3.24 KBmokko
#168 interdiff.161-168.txt1.61 KBmokko
#168 607028.168.README.patch3.38 KBmokko
#161 607028.161.README.patch3.18 KBmokko
#156 607028.156.README.patch3.39 KBdeviantintegral
#150 607028-150.patch3.49 KBmokko
#150 interdiff.txt2.03 KBmokko
#145 607028-145.patch3.5 KBmarcvangend
#142 607028-142.patch3.59 KBmokko
#138 607028-138.patch3.51 KBmarcvangend
#135 607028-135.patch3.54 KBjhodgdon
#134 607028-134.patch3.55 KBjhodgdon
#125 607028-124.patch3.36 KBjhodgdon
#118 607028-118.patch3.34 KBjhodgdon
#111 607028.111_README.patch3.11 KBdeviantintegral
#111 607028.91-111-interdiff_README.patch3.74 KBdeviantintegral
#110 README.txt2.91 KBXano
#105 README.txt2.88 KBXano
#102 607028.102_README.patch1.22 KBXano
#95 607028.95_README.patch3.17 KBmarcvangend
#91 607028.91_README.patch3.15 KBdeviantintegral
#78 607028-78.patch3.81 KBdeviantintegral
#71 607028-71.patch3.76 KBdrifter
#70 607028_README.txt3.46 KBdeviantintegral
#70 607028_README-diff-66-70.txt1.24 KBdeviantintegral
#66 607028_README-diff-63-66.txt3.16 KBdeviantintegral
#66 607028_README.txt3.54 KBdeviantintegral
#63 607028_README.txt3.38 KBdeviantintegral
#58 0607028_README.txt3.45 KBuNeedStuff
#57 607028_README.txt3.1 KBdeviantintegral
#57 607028_README-diff-53-56.txt1.61 KBdeviantintegral
#54 607028_README_09.txt3.3 KBuNeedStuff
#53 607028_README.txt3.45 KBdeviantintegral
#53 607028_README-diff-49-53.txt2.17 KBdeviantintegral
#49 607028_README.txt3.13 KBdeviantintegral
#49 607028_README-diff-45-49.txt4.36 KBdeviantintegral
#45 607028_README.txt3.14 KBdeviantintegral
#45 607028_README-diff-40-45.txt3.64 KBdeviantintegral
#40 607028_README.txt1.82 KBdeviantintegral
#38 607028_README.txt1.8 KBdeviantintegral
#37 607028_README_2.txt1.88 KBmarcvangend
#36 607028_README_1.txt1.88 KBmarcvangend
#34 607028_README.txt1.84 KBdeviantintegral
#28 10202009-README.txt1.54 KBuNeedStuff
#26 20091020-marcvangend-README.txt1.28 KBmarcvangend
#22 20091019-tgeller-README.txt1.19 KBtgeller
#21 20091019-tgeller-README.txt1.19 KBtgeller
#19 drupal.patch0 bytessun
#17 607028_README.txt2.11 KBdeviantintegral
#13 README.txt2.08 KBdeviantintegral
#3 607028_3.dont_hack_core.patch273.12 KBcweagans
#1 607028_1.dont_hack_core.patch278.33 KBcweagans
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

cweagans’s picture

Status: Active » Needs review
Issue tags: +Quick fix, +Documentation
FileSize
278.33 KB

Woo! 278k patch engage!

Status: Needs review » Needs work

The last submitted patch failed testing.

cweagans’s picture

Status: Needs work » Needs review
FileSize
273.12 KB

This one actually applies >.<

Status: Needs review » Needs work

The last submitted patch failed testing.

cweagans’s picture

Status: Needs work » Needs review

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

moshe weitzman’s picture

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.

deviantintegral’s picture

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

sun’s picture

Status: Needs review » Closed (won't fix)
webchick’s picture

Status: Closed (won't fix) » Needs review

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?

Status: Needs review » Needs work

The last submitted patch failed testing.

webchick’s picture

Title: Don't Hack Core message at file headers » Impart development best-practices in core
Status: Needs work » Active

Cross-posted. Adjusting title.

webchick’s picture

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.

deviantintegral’s picture

FileSize
2.08 KB

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.

deviantintegral’s picture

Status: Active » Needs review

Status: Needs review » Needs work

The last submitted patch failed testing.

cweagans’s picture

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

deviantintegral’s picture

Status: Needs work » Needs review
FileSize
2.11 KB

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?

webchick’s picture

Component: base system » documentation

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.

sun’s picture

FileSize
0 bytes

This will solve it.

jhodgdon’s picture

Status: Needs review » Needs work

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

tgeller’s picture

FileSize
1.19 KB

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

tgeller’s picture

FileSize
1.19 KB

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

webchick’s picture

Title: Impart development best-practices in core » Add README.txt to core

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

jhodgdon’s picture

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.

winston’s picture

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.

marcvangend’s picture

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.

jhodgdon’s picture

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.

uNeedStuff’s picture

FileSize
1.54 KB

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.

marcvangend’s picture

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.

codeknitter’s picture

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.

deviantintegral’s picture

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.

marcvangend’s picture

@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.)

jhodgdon’s picture

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

deviantintegral’s picture

Status: Needs work » Needs review
FileSize
1.84 KB

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.
marcvangend’s picture

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?

marcvangend’s picture

FileSize
1.88 KB

Ouch, forgot the attachment.

marcvangend’s picture

FileSize
1.88 KB

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

deviantintegral’s picture

FileSize
1.8 KB

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.

jhodgdon’s picture

Status: Needs review » Needs work

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:

* Don't hack Drupal core:
   Place new modules and themes in sites/all/modules and
   sites/all/themes.
   See http://drupal.org/node/144376

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

* Don't modify core Drupal files (i.e. "hack core") -- see http://drupal.org/node/144376
* Place new modules and themes in sites/all/modules and sites/all/themes.

c) Also in "write code":

* Extend Core Functionality ("modules") to Drupal:

Minor suggested change:

* Extend Core Functionality (add "modules") to Drupal:

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:

* Program with Drupal's API and hooks:
See http://api.drupal.org/
http://drupal.org/node/326
http://api.drupal.org/api/group/hooks/7
deviantintegral’s picture

Assigned: cweagans » Unassigned
Status: Needs work » Needs review
FileSize
1.82 KB

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

jhodgdon’s picture

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

marcvangend’s picture

#40 looks good. RTBC AFAIC.

webchick’s picture

USE AND CONFIGURE YOUR DRUPAL SITE
----------------------------------
...
 * To join the Drupal community:
   See http://drupal.org/contribute

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.

   http://drupal.org/getting-started/5/install-contrib/themes
...
   http://drupal.org/getting-started/5/install-contrib/modules

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:

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

 * To install, upgrade, and maintain Drupal:
   See INSTALL.txt and UPGRADE.txt in the same directory as this document.
 * To create and improve your Drupal site:
   See http://drupal.org/getting-started
 * To join the Drupal community:
   See http://drupal.org/contribute

to something like:

USE AND CONFIGURE YOUR DRUPAL SITE
----------------------------------
Drupal ships with a baseline framework to handle low-level actions such as logging in and managing content, upon which additional features may be added through the use of "modules." The core Drupal download ships with several modules to perform standard tasks such as image uploading and searching, and more contributed modules are available from the Drupal.org website, to enable additional functionality.

 * To install, upgrade, and maintain Drupal:
   See INSTALL.txt and UPGRADE.txt in the same directory as this document.
 * To learn the basics of how to create and manage your Drupal site:
   See http://drupal.org/getting-started
 * For how-to guides, videos, and other resources for extending Drupal with contributed modules:
   See http://drupal.org/contribute

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

jhodgdon’s picture

Status: Needs review » Needs work

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

deviantintegral’s picture

Status: Needs work » Needs review
FileSize
3.64 KB
3.14 KB

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.

Xano’s picture

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

marcvangend’s picture

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://".

jhodgdon’s picture

Status: Needs review » Needs work

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.

deviantintegral’s picture

Status: Needs work » Needs review
FileSize
4.36 KB
3.13 KB

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?

dww’s picture

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

marcvangend’s picture

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.

jhodgdon’s picture

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:

 * Place new modules and themes in sites/all/modules and
   sites/all/themes.

should also be in the "CHANGE THE LOOK AND FEEL OF YOUR DRUPAL SITE" section.

deviantintegral’s picture

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.
uNeedStuff’s picture

FileSize
3.3 KB

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.

deviantintegral’s picture

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.

webchick’s picture

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.

deviantintegral’s picture

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?

uNeedStuff’s picture

FileSize
3.45 KB

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.

deviantintegral’s picture

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".
uNeedStuff’s picture

# 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

deviantintegral’s picture

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

dww’s picture

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: Move all core Drupal files under a /core folder to improve usability and upgrades is done...

deviantintegral’s picture

FileSize
3.38 KB

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

deviantintegral’s picture

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

 USE AND CONFIGURE YOUR DRUPAL SITE
 ----------------------------------
 
-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
-modules to provide additional functionality such as image uploading, search, and
-content translation. More contributed modules are available from the drupal.org
-to enable additional functionality.
+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.
- * Create and improve your Drupal site:
+   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
@@ -36,6 +38,8 @@
    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
  • 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 LOOK AND FEEL OF YOUR DRUPAL SITE
 --------------------------------------------
@@ -45,11 +49,12 @@
 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
  • "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.
uNeedStuff’s picture

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.

deviantintegral’s picture

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!

uNeedStuff’s picture

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.

sepeck’s picture

removed version specific # in two urls per request of jhodghon

jhodgdon’s picture

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

deviantintegral’s picture

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.

drifter’s picture

FileSize
3.76 KB

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

drifter’s picture

Status: Needs review » Reviewed & tested by the community

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

deviantintegral’s picture

Status: Reviewed & tested by the community » Needs work

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

jhodgdon’s picture

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

jhodgdon’s picture

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:

* Change the default themes with those provided in core:
   http://drupal.org/getting-started/6/admin/build/themes

How about:

* Change which themes are used on your site and configure themes:
  (whatever the new URL alias is)

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

Damien Tournoud’s picture

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

jhodgdon’s picture

How about the license too?

deviantintegral’s picture

FileSize
3.81 KB

Here is a patch which:

deviantintegral’s picture

Status: Needs work » Needs review
jhodgdon’s picture

Status: Needs review » Needs work

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?

jhodgdon’s picture

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

LeeHunter’s picture

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.

webchick’s picture

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/?"

deviantintegral’s picture

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?

deviantintegral’s picture

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.

frankcarey’s picture

I think the latest version is pretty much a winner. I can see the worry of a document going out of date and being hard to maintain, but I think this is an important piece of documentation; Perhaps one that should live both in a README.txt file AND online in the handbook documentation, perhaps even the main page.

It could just be an identical document, with just a few formatting changes to make it text file appropriate. Who knows, maybe a simple script to convert it with one command, or if we could finally use Markdown for Documentation, it would be a simple cut and paste operation. :) IT could be updated right before every drupal bug fix release.

So, how about basically saving a cached copy of the online handbook page version of this document in README.txt, and then just linking to the online version at the top of the file? That way there is a solid offline version, but an up to the minute version is available as well if links go dead, or a reorganization of documentation needs to happen? It should also certainly be easier to maintain something like this online, where the barrier to action is much lower.


For the most up-to-date version of this document, see: http://drupal.org/handbook 

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
------------
frankcarey’s picture

Also, to take things one step further, might it make sense to use this document in place of the default frontpage documentation when you first install drupal? It would certainly get a lot of attention there. I think this info is really that valuable.

I know years ago, when I was searching for a CMS, I would have loved to be able to install it and have this type of stuff pop up immediately so I could get a feel for it and decide if it was the right fit. For many, choosing a CMS is trial and error. So, getting folks on the right track quickly really helps the people we all used to be, understand the unintuitive ways our present-selves make things happen in drupal.

frankcarey’s picture

RobLoach's Unspoken Rules of Drupal: pretty succinct :) http://robloach.net/node/128

mcrittenden’s picture

Sub.

marcvangend’s picture

Wow, 37 weeks of silence here. I hope the restructuring of the documentation has settled down by now. We already got very far... let's wrap this up and get it committed. (This post is just to wake us all up. I'll try to work on the patch in the coming days, but don't let that stop anyone from doing the same.)

deviantintegral’s picture

Status: Needs work » Needs review
FileSize
3.15 KB

The attached patch:

  • Removes all legacy URLs
  • Only points users to "landing pages" except for the "Don't hack core" page
  • Notes that Bartik is now the default theme instead of Garland (w00t!)
  • Reduces the number of bullet points, as those will be covered by following the associated links
  • Places the link about hacking core for both themers and module developers, since that was the original push behind this issue anyways. Only putting the link in the "developers" section won't grab the attention of those inclined to hack theme_* functions.

Every URL is a clean url, except for the hacking core URL. Can we get a clean URL for that page?

Here is a list of every URL in the document:

deviantintegral’s picture

Issue tags: -Quick fix

This is no longer really a "quick fix" :)

marcvangend’s picture

I think it looks very good, just one small thing...

When will http://api.drupal.org/ default to the D7 documentation? Right now, it takes me to D6. I think I remember that api.drupal.org only switched from D5 to D6 some 6 months after version 6.0 was released. If the same is going to happen with D7, I think we should link to http://api.drupal.org/api/drupal/7 instead of http://api.drupal.org/.

webchick’s picture

That might not be a bad idea regardless; when Drupal 8 (and Drupal 12 and 16... ;)) comes out, that link is still going to need to work.

marcvangend’s picture

FileSize
3.17 KB

Same patch as in #91, now links to http://api.drupal.org/api/drupal/7 instead of http://api.drupal.org/.

Xano’s picture

This is a short review focused on writing style and usability.

+++ README.txt
@@ -0,0 +1,74 @@
+website. Drupal includes several "modules" for common functionality such as

Why do we use quotes here? We mean modules, so we should just say modules and not make it look like this is a quote, or we say modules, but actually mean something different.

+++ README.txt
@@ -0,0 +1,74 @@
+drupal.org website to enable additional functionality.

Can we link to the modules page at drupal.org directly? Just using "drupal.org" is safer in case we change the URL structure, but less usable.

+++ README.txt
@@ -0,0 +1,74 @@
+ * Download contributed modules in sites/all/modules to extend Drupal's

I'm no native speaker of English, but shouldn't this be "Download contributed modules to (...)"?

+++ README.txt
@@ -0,0 +1,74 @@
+ * Learn about Developing for Drupal:
+   http://drupal.org/contributors-guide
+ * Use Drupal's API and hooks:
+   http://api.drupal.org/api/drupal/7
+ * Don't modify core Drupal files ("hack core"):
+   http://drupal.org/node/144376

* Developing for Drupal:
http://drupal.org/contributors-guide
* Code documentation
http://api.drupal.org/api/drupal/7
* Don't modify Drupal's code files ("hack core"):
http://drupal.org/node/144376

The first two items are a bit shorter and more to the point. I edited the last one so it doesn't only apply to core (because it shouldn't) and it explicitely mentions code files, which (I hope) implies files that contain logic (so no templates).

I also recommend removing the quotes from theme names (and modules for that matter) as per http://en.wikipedia.org/wiki/Quotation_mark#Incorrect_usage. In short: quotes are not for emphasis.

Powered by Dreditor.

xmacinfo’s picture

Status: Needs review » Needs work

As per Xano comments, changing the status.

Adding a README.txt is welcome. I like the content and the layout.

marcvangend’s picture

Xano, usually I would agree with your remarks about the quotes, but a README.txt is different. The Wikipedia page you're linking to says "Quotes are sometimes used for emphasis in lieu of underlining or italics". Obviously, we can't put underlined or italic text in a .txt file.

Let's have a look this line for instance:
Drupal includes several "modules" for common functionality such as managing content and user accounts.
We're writing this for people who are completely new to Drupal. Without the quotes, it seems that we assume that the reader knows what modules are. We don't want the reader to think "WTF? I'm half way throught the README and I already don't understand what they're talking about. This Drupal thing is too complicated for me." With the quotes, the reader will think "Aha, that's a new concept, let's read on and find out what that means." I would normally use italics in a situation like this, but if we can't, quotes are better than nothing.

Eric_A’s picture

Apparently the bot does not care, but
You must not add a space between $Id and $ when you commit the keyword for the first time.

Xano’s picture

Good point.

But adding quotes does not solve our problem. It may lead the reader to think "Okay, modules. This is new for me, so I should pay attention", but what we really want is explain the reader what modules really are, the first time we mention them.

What about

Drupal includes several modules (plugins for extra functionality) (...)

If we use this explanation, we should alter the entire paragraph a bit, because Drupal core and contrib are a bit mixed up and the word "module" is repeated quite a few times:

Drupal core (drupal-x.xx.tar.gz) has what you need to get started with your
website. It includes several modules (plugins for extra functionality) for
common features, such as managing content, user accounts, image uploading, and
search. Additional features are added to Drupal by enabling additional modules.

More contributed modules (not included with Drupal core) are available from the
drupal.org website to enable additional functionality.

* This text makes a clear distinction between core and contrib. The difference between those is something that confuses a lot of newcomers.
* It also explains the concept of modules within Drupal. They extend functionality, and you usually need to enable additional modules to enable additional functionality.
* I removed the (very vague) distinction between required and optional modules in core. I believe we don't want to scare newcomers with the word "required" (or the concept thereof) any more than we have to. The modules page will already do this for us with the "Core - required" package.

marcvangend’s picture

Xano: excellent text, I think it's very clear.

I'm just not sure about the "More contributed modules" part. Contributed modules have not been mentioned before, so "More contributed modules" doesn't really make sense. I think it should either be "More modules" or "Contributed modules".

As fas as I can see, the README.txt didn't really make a distinction between required and optional core modules, but it did indicate that not all core modules are enabled by default. Your text still does that, so that's good. (BTW, in D7, the "Core - required" package doesn't even exist anymore on the module page. Required modules are simply listed under the Core package, with the description "Required by: Drupal".)

Regarding the point you made earlier: there already is a direct link to the modules page (http://drupal.org/project/modules). It's a deliberate choice to provide links as bullets below each paragraph, not inline. In the phrase "available from the drupal.org website", drupal.org is meant as an identifying name, not as a link.

Xano’s picture

FileSize
1.22 KB

* Unnecessary quotes have been removed.
* I replace the 'introduction to modules' paragraph with my version from #100, but changed "More contributed modules" to "Contributed modules" as per @marcvangend in #101.
* I made the lists about themes consistent with the one about modules.

Xano’s picture

Status: Needs work » Needs review

I forgot to set the status.

marcvangend’s picture

Status: Needs review » Needs work

Bart, that's the wrong patch :-D

Xano’s picture

Status: Needs work » Needs review
FileSize
2.88 KB

I suck at adding new files to patches. Here's the entire README.txt from #102.

I also fixed the $Id$ mentioned in #99.

jhodgdon’s picture

Status: Needs review » Needs work

Reviewing the readme attached in #105:

Contributed modules (not included with Drupal core) are available from the
drupal.org website to enable additional functionality. 

a) What follows this paragraph is a list. Every list should be proceded by a description of what's in the list and a colon. In this case, the list is not really related to this paragraph, so we need a new paragraph, something like: "More information about installing and configuring Drupal:" Also, there shouldn't be a blank line between this new line and the following list.

Drupal contains a theme system to separate the look and feel of a website from
its functionality and content. By default, Drupal uses the Bartik 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.

b) Technically, Seven is only the default if you install using the standard install profile. If you install using the expert install profile, you don't get Seven. And what if someone uses a different install profile entirely? I think we should say "If you use the standard install profile, Drupal defaults to using the Bartik..." or something like that.
c) This paragraph should end in a : because what follows is a list of resources, and there shouldn't be a blank line between the : and the list.

Before writing a new module, be sure to search the Drupal website for a module
which meets your requirements.

d) which -> that
e) Again, needs a line ending in a : before the list that follows this paragraph.

* Code documentation
   http://api.drupal.org/api/drupal/7

f) documentation should be followed by a : so that this line is parallel to the other ones. Also, "code documentation" seems kind of vague. How about "Documentation on Drupal's core functions"?

Xano’s picture

b) What if we just remove the theme names from the text entirely? For new users, the names of the themes they will see right after the installation doesn't really mean much and I don't expect it matters much either. They want to know what they can do with Drupal and how to do it.

f) I believe a.d.o already indexes some contributed modules. We should only focus on core when we're absolutely sure the thing we're talking about will only apply to core during Drupal 7's lifespan. Also, the API docs don't only focus on functions. They contain documentation about Drupal's code, whether that means functions, classes, methods, files or constants. It's code and it's documented.

jhodgdon’s picture

I'm OK with removing the names of the themes. But...

"By default, Drupal uses the Bartik 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."

To customize ***further***? What does that mean in this context?

f) You are correct, a.d.o does contain some contrib modules and probably will have more in the future.... On drupal.org the links to a.d.o say "API reference", and that's also the title of the landing page of a.d.o. So let's use the same phrase in the README.

sepeck’s picture

@91 - alias added. let me know if you want it to be different.
http://drupal.org/best-practices/do-not-hack-core

Xano’s picture

Status: Needs work » Needs review
FileSize
2.91 KB

* Changed the URL to the don't hack core page so it now uses the alias as per #109. Thanks to @sepeck for the alias!
* Changed the theme info to "By default, Drupal uses one theme for displaying content to users, and uses a specialized theme for the administrative interface."
* Changed "which meets" to "that meets" as per @jhodgdon in #106.
* Changed "Code documentation" to "API documentation".

Some more thoughts:
* Shouldn't "To customize Drupal's display further" be "To further customize Drupal's display"?
* Can we replace all occurences of the Drupal website with the actual address (Either drupal.org or http://drupal.org)? It makes no sense to use a different phrase, while the URL itself is shorter and more helpful.

deviantintegral’s picture

Shouldn't "To customize Drupal's display further" be "To further customize Drupal's display"?

I agree with "To further...", so I've changed that in the attached patch.

Can we replace all occurences of the Drupal website with the actual address (Either drupal.org or http://drupal.org)? It makes no sense to use a different phrase, while the URL itself is shorter and more helpful.

My original intent with "the Drupal website" was to distinguish it from drupal.com, thinking that many newcomers might get them confused. That's probably less of an issue post-redesign, but I'm open to changing that.

I've attached a diff compared to the patch at #91 for anyone else reviewing this.

Status: Needs review » Needs work

The last submitted patch, 607028.91-111-interdiff_README.patch, failed testing.

marcvangend’s picture

Status: Needs work » Needs review

(overriding testbot)

jhodgdon’s picture

Status: Needs review » Needs work

OK, here's another review:

a)

and join the
+Drupal community at http://drupal.org/contribute.

We should point people to http://drupal.org/community to "join the Drupal community". It's one level up from the Contribute page, and more comprehensive (will lead them to IRC, forums, etc.).

b)

+
+ * Know your rights when using Drupal:
+   See LICENSE.txt in the same directory as this document.
+ * Learn about the Drupal trademark and logo policy:
+   http://drupal.com/trademark

ALL lists in documentation should be preceded by a line telling what the list is and ending in a colon. There are several in this document, including the one above, that aren't. This violates our documentation standards.

c)

+Drupal core (drupal-x.xx.tar.gz) has what you need to get started with your
+website.

How about explaining what "drupal core" is, rather than just giving the file name? (e.g. "what you get when you download Drupal" or something like that). Also, in other .txt files, we refer to x.yy not x.xx

d)

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

Again, "by default" depends on which install profile you use. For instance, the "expert" profile doesn't set up an admin theme. Also, when you get to that last paragraph, why does it say "to further customize" when there's no previous customization that has been discussed? It made me want to look back in that paragraph and find out what customization I had already learned about, very confusing.

e)

+ * API documentation

Needs to be followed by :

joachim’s picture

Overall this looks great :)

> How about explaining what "drupal core" is, rather than just giving the file name? (e.g. "what you get when you download Drupal" or something like that). Also, in other .txt files, we refer to x.yy not x.xx

Furthermore, if I'm reading this file, I have already unzipped that file, surely!

> By default, Drupal uses one theme for displaying
+content to users, and uses a specialized theme for the administrative
+interface.

I'm not sure what this sentence is for.

Perhaps this gets to the intended meaning better:

"This is demonstrated in the difference in appearance between content display and administration pages."

jhodgdon’s picture

Please lets not talk about the admin theme being different from the outward facing theme on a site. This is only the default behavior if you have used the "standard" installation profile, and it might be confusing for someone to read this if they used any one of hundreds of other available installation profiles, including the "minimal" profile included with the Drupal distribution.

What we should do instead is say something about what themes do, and cut out this whole setntence.

jhodgdon’s picture

Assigned: Unassigned » jhodgdon

I also just noticed the proposal above has some trailing whitespace at ends of lines. Anyway, I'm making a new version...

jhodgdon’s picture

Assigned: jhodgdon » Unassigned
Status: Needs work » Needs review
Issue tags: -Documentation
FileSize
3.34 KB

Here's a new patch... (and removing the documentation tag - this is in the documentation component, the tag is not necessary).

joachim’s picture

Status: Needs review » Needs work

Just nitpicking now ... ;)

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+your website. It includes several modules (functionality plugins) for common

That's just defining one jargon word in terms of two others... I think it's already clear from the rest of the sentence that modules are things which add features. We can lose the parenthesis.

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+(put them in sites/all/themes).

Should we have a matching bit for modules?

And should we have a links list for the themes bit too?

Powered by Dreditor.

jhodgdon’s picture

a) We do need to provide some definition for what modules are I think.... here's the current text:

...[Drupal core] has what you need to get started with your website. It includes several modules (functionality plugins) for common features, such as managing content, user accounts, image uploading, and search, and there are many configuration options.

Hmmm.... I think you are right, the "(functionality plugins)" can be left out... but maybe we should say

It includes several "modules", which provide functionality such as managing content, user accounts, image uploading, and search, and there are many configuration options.

Then in the theme section, we should put "themes" in quotes, to indicate it's a Drupal-specific term that we are defining/illustrating? We need some way to indicate that something might be an unfamiliar word, as was discussed above...

b) We do say where to put modules, in the corresponding item telling where to download them, in the Configuration section bullet list. But there was only one bullet for themes (where to download them), so I didn't think it made sense to make a bullet list. Thoughts?

joachim’s picture

> so I didn't think it made sense to make a bullet list. Thoughts?

Good reasoning. But perhaps we could add a link to the theming guide docs page?

> Then in the theme section, we should put "themes" in quotes

I really balk at scare quotes :/ Will scratch my head some more over this one.

jhodgdon’s picture

The section about writing your own code has a link to the theming guide.

joachim’s picture

Okay, 'themes' is definitely a word with a Drupal-specific meaning, and 'plug-in' is a well-defined and easily-understood word. So I like what we have in the patch:

themes (plugins that control the look and feel of the site)

so let's match that with:

modules (plugins which provide extra functionality)

Though I note that my dictionary has 'plug-in' and not 'plugin'. And then I think we're done :)

> The section about writing your own code has a link to the theming guide.

Oh yeah... duh :/

sun’s picture

FWIW, "extensions" is a more proper name for the superset meaning modules, themes, and profiles.

WP uses "plugin", Firefox uses "add-on", Joomla uses "extension". From all of those, Joomla's extension terminology and meaning made most sense to me all of the time.

jhodgdon’s picture

Status: Needs work » Needs review
FileSize
3.36 KB

OK, here's a new patch.

jhodgdon’s picture

oops, I cross-posted with #124. I agree, extensions is a better word than plugins. I don't have time to make a new patch, can someone else? (Make sure to get the word wrapping to 80 characters...)

Xano’s picture

Status: Needs review » Needs work
+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+download additional contributed themes from http://drupal.org/project/themes
+(put them in sites/all/themes).

Where's the links to "Don't hack core!" gone to? Themes have code files too. Code files that come back to haunt you after an update if you hack them.

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+CUSTOM CODE

Again, themes contain code too. Let's call modules development something like "Custom functionality", because functionality is what modules offer.

It might be good to keep a separation between themes and modules here, as in practice it turns out most people see (because they expect) a difference.

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+Drupal contains an extensive API that allows you to extend and modify Drupal's
+core functionality, as well as its look and feel. This is done by implementing

Not only core's functionality can be modified and overriden, but contrib's as well.

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+ * API reference:

I already said it, but I still think we should go for "API documentation", rather than "API reference". It's less abstract and I believe conveys the message more clearly.

Powered by Dreditor.

BTW: +1 for sun's suggestion of using "extensions" instead of "plugins". Plugins just plug in, but don't have to do anything. "Extensions" actually tells you they provide more of something.

jhodgdon’s picture

I moved *all* of the coding stuff to the Custom Code section -- both themes and modules, because I agree with you: both themes and modules have code, and I thought they should be treated together. That is why it's called "CUSTOM CODE" not "CUSTOM FUNCTIONALITY".

Xano’s picture

I understand why you did that. My reasoning was that most users expect modules to be 'real' code (as in programming, difficult and way over their heads), while theming is considered rather easy, mostly because it can be done using just HTML and CSS.

jhodgdon’s picture

Well, maybe you can think of a better heading than Custom Code, which would convey this? If it were called "Custom Themes and Modules", would that help? I just thought it made more sense to put all the information about custom stuff together, since pretty much everything in it applies to both modules and themes, rather than duplicating it.

Xano’s picture

The separation between functionality, design and writing your own code was a good idea, because the section about code has a different target audience. I went over your last version and found some minor issues:

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+LOOK AND FEEL

This sounds too abstract. Yes, *I* know what it means, but it's an English expression and most Drupal users don't have English as their first language, so we should avoid concept of "feelings". What about just "Looks" or "Design"?

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+CUSTOM CODE

"Custom modules and themes"

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+overriding "theme functions", "theme templates", and CSS directives in

"CSS rules" is a more common term, I believe.

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+themes. You can create your own completely custom modules and themes, but keep
+in mind that there are thousands of contributed modules and themes available for
+download. So before writing a new module or theme, be sure to search for an
+existing module or theme that meets your requirements.

"Before you create your own module or theme, search between the thousands of existing modules or themes to find what you need. This saves time and improves the quality of existing code."
1) It still advises readers to search first
2) but it also tells them why they should do that.
3) It's not just about contrib. I have seen people replicate core features, just because they didn't know they existed.
4) Less is more, especially when reading manuals.

Powered by Dreditor.

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+LOOK AND FEEL

This sounds too abstract. Yes, I know what it means, but it's an English expression and most Drupal users don't have English as their first language, so we should avoid "feel". What about just "Looks or "Design"?

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+CUSTOM CODE

"Custom modules and themes"

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+overriding "theme functions", "theme templates", and CSS directives in

"CSS rules" is a more common term, I believe.

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+themes. You can create your own completely custom modules and themes, but keep
+in mind that there are thousands of contributed modules and themes available for
+download. So before writing a new module or theme, be sure to search for an
+existing module or theme that meets your requirements.

"Before you create your own module or theme, search between the thousands of existing modules or themes to find what you need. This saves time and improves the quality of existing code."
1) It still advises readers to search first
2) but it also tells them why they should do that.
3) It's not just about contrib. I have seen people replicate core features, just because they didn't know they existed.
4) Less is more, especially when reading manuals.

+++ README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,77 @@
+download additional contributed themes from http://drupal.org/project/themes

I'd make this a one-item list like everywhere else, just for consistency and readibility. The other lists indicate 'actions', just like the link to the drupal.org themes page.

Powered by Dreditor.

jhodgdon’s picture

OK. I dont' have time to make another patch right now, but these suggestions (#131) seem pretty good (plus or minus a few grammar/style points).

joachim’s picture

> This sounds too abstract. Yes, *I* know what it means, but it's an English expression and most Drupal users don't have English as their first language, so we should avoid concept of "feelings". What about just "Looks" or "Design"?

Well the UI calls it 'Appearance', so why not do the same here? That way we're consistent.

jhodgdon’s picture

Status: Needs work » Needs review
FileSize
3.55 KB

Here's a new patch. I think all of the concerns expressed since the last patch have been addressed. Hopefully. :)

jhodgdon’s picture

FileSize
3.54 KB

Whoops, hadn't quite saved my latest version. Here's the same patch, minus one comma.

joachim’s picture

Status: Needs review » Reviewed & tested by the community

Looks good to me! :D

webchick’s picture

Status: Reviewed & tested by the community » Needs work

Wow, GREAT work on this, all! This has evolved quite a bit since the last time I looked at it.

+Drupal contains an extensive API that allows you to extend and modify Drupal's
+functionality, as well as its appearance. This is done by implementing "hooks"
+in modules; implementing "theme hooks" in modules and themes; and overriding
+"theme functions", "theme templates", and CSS rules in themes. 

I'm not quite sure where/when this got introduced, but the last paragraph here is needlessly and suddenly throwing ALL KINDS of jargon at people that they really, really don't need to know when they're still at the "what is Drupal?" stage. While the first three sections are very good about using plain English language and skimping on nitty-gritty details in favour of documentation, this fourth section is going way over the top. I know actual themers who don't know what theme hooks are.

I do think that it is important to mention the word "hooks" in this paragraph, since Drupal people talk about them a lot. Beyond that, I don't feel further detail is necessary. It's more appropriate here to talk in general terms about Drupal's extensibility, and how the entire system is architected to be malleable and easy to customize, etc.

And I'd move any details about custom theming to the "Appearance" paragraph where it belongs more cleanly ("You can also create your own custom themes", along with a link to resources.) That's the first question people are likely to have about their site's appearance is "How do I change it to my own design?" Let's answer it in-place.

I like the shout-out to go join the larger community. :)

Then one other tiny nitpick:

drupal-x.yy.tar.gz

Let's make it just x.y. Drupal 7 won't have a .yy until Drupal 7.10 which will be months after 7.0 comes out, so that extra level of detail is confusing and looks like a typo.

If any of this is rehashing discussions had above where there were good reasons not to do it this way, let me know.

marcvangend’s picture

FileSize
3.51 KB

I agree with Webchick.

People reading this document will not know if what they need requires a ready made theme or a custom theme. They only know which task they need to get done. It makes more sense to put the custom themes part in the 'Appearance' paragraph. (Hmm, that sounds just like what I wrote in #26 :-)) I did leave in "overriding functions, templates and CSS" because I think that concept is as important to theming as "hook" is to writing modules.
Before you ask: I do think that the 'Developing for Drupal' paragraph (as I called it in this patch) needs to be separate from 'Configuration and Features', because I often see that experienced programmers who are new to to Drupal, assume that building a Drupal site equals writing custom modules.

marcvangend’s picture

Status: Needs work » Needs review
joachim’s picture

Looks great!

One very last nitpick ;)

Elsewhere in the file we're using the Oxford comma, so it needs one here after the 'and':

+functions, templates and CSS.

mokko’s picture

In the contents the last item is called "Custom themes and modules" while the last heading is called "DEVELOPING FOR DRUPAL". Otherwise good text for beginners with the right level of terseness.

mokko’s picture

FileSize
3.59 KB

I don't know exactly what's the Oxford comma, but joachim seems to be right. I changed comma as suggested as well as heading in the contents.

Is it done now?

Status: Needs review » Needs work

The last submitted patch, 607028-142.patch, failed testing.

joachim’s picture

Status: Needs work » Needs review

Bot is on crack today. RTBC from me.

Perhaps let jhodgdon give final approval :)

marcvangend’s picture

FileSize
3.5 KB

#140, #141: you're both right, good catch.

Bot is not on crack, bot just likes unix line endings. Same patch as #142, different line endings.

cweagans’s picture

Status: Needs review » Needs work

Couple more changes:

+It includes several modules (extensions that add functionality)
+for common website features, such as managing content, user accounts, image
+uploading, and search, and there are many configuration options.

Can we say "configurable options" here? I think it better communicates what you're trying to say here.

+features by disabling modules. Also, thousands of contributed modules (for
+functionality not included with Drupal core) are available for download.

New Drupal user says: "Available for download where?"

+theme settings (colors, logos, using a different theme for administrative tasks,
+etc.).

The first use of parenthesis in this paragraph was okay, but this one is incorrect. It should be like this: " theme settings, such as colors, logos, or using a different theme for administrative tasks."

+a "hook". Before you create your own module, try searching at http://drupal.org
+-- you may find that an existing core or contributed module can be used to meet
+your requirements. Or if it comes close, maybe you can add a feature to an
+existing module and contribute it back to the project.

This should be written: Before you create your own module, try searching at http://drupal.org. You may find that an existing core or contributed module can be used to meet your requirements. If you find a module that comes close, consider adding your feature to the module and contributing it back to the project.

marcvangend’s picture

Can we say "configurable options" here? I think it better communicates what you're trying to say here.

I think "configurable options" is a pleonasm. Non-configurable options don't exist at all, do they? That said, I'm not sure what "configuration options" means either.

New Drupal user says: "Available for download where?"

The link to the download page is in the bulleted list right below that sentence. Isn't that good enough?

jhodgdon’s picture

RE #147 - What I was trying to get across is that there are many ways to configure your site, i.e. "many configuration options".

We have the link to where to download the modules directly below in the bullet list.

mokko’s picture

I am okay with configuration options. It is better than only configuration(s) and only options, but marcvangend is right that it is not perfect. Maybe we should make two sentences out of it. Something along the line of

Drupal core (what you get when you download and unzip a drupal-x.y.tar.gz file from http://drupal.org/project/drupal) has what you need to get started with your website. It includes several modules (extensions that add functionality) for common website features, such as managing content, user accounts, image uploading, and search. Core comes with many options which allow site-specific configuration.

Other ideas: Do we really need to say that one can enable, disable and remove additional (core) modules? I think that is not necessary detail. I would just leave that sentence out. The main idea is that there are different core modules and there is configuration to change functionality.

I would add a little bit at the beginning to make it easier to follow:

In addition to core modules, there are thousands of contributed modules (for
functionality not included with Drupal core) available for download.

I do prefer the period/full stop in stead of the hyphen as suggested above.

So let me see if I can make a patch with correct line endings... for practice, I guess. I will edit in in a minute.

mokko’s picture

FileSize
2.03 KB
3.49 KB

This time I edited the patch with emacs under cygwin and made an interdiff. How does the bot thinks about this? How do you think about it?

mokko’s picture

Status: Needs work » Needs review

I guess I need to change the status to find out what the testbot thinks.

Status: Needs review » Needs work

The last submitted patch, interdiff.patch, failed testing.

dww’s picture

@mokko: You'll have a lot more luck if up upload interdiffs as foo.interdiff.txt instead of foo.interdiff.patch, since they're not really patches, and that confuses the bot.

mokko’s picture

yes. Understood. Thanks anyway! I had forgotten it. Are you implying that it is important to fix this? Or is it clear enough to everybody reviewing this thing?

deviantintegral’s picture

Assigned: Unassigned » deviantintegral

The patch in #150 is missing a blank line, confusing patch. Will upload a new file shortly.

deviantintegral’s picture

Assigned: deviantintegral » Unassigned
Status: Needs work » Needs review
FileSize
3.39 KB

Here's a patch that:

  • Adds a newline to the end of the file, restoring the don't hack core URL when applying the patch.
  • Removes a newline between line 70 and 80 (the line is exactly 80 characters).
  • Removes some leftover spaces at the end of lines 33, 34, 53, and 54.
webchick’s picture

This is looking really good. A couple more small nit-picks:

+Drupal contains a theming system to separate the appearance of your website from
+its functionality and content. You can activate one or more themes (extensions
+that control the appearance of the site) on your website, and you can customize
+theme settings such as colors, logos, or using a different theme for
+administrative tasks.

A person trying to figure out "What is Drupal?" doesn't care about a "theming system" and how it "separates functionality and content." That's purely a developer distinction. This bit doesn't belong in README.txt, nor does the fact that you can activate "one or more" themes (advanced usage only).

What does belong here is something to the effect of:

"Drupal's appearance can be customized with the use of themes (extensions that control the fonts, colors, and layout of the site). Drupal offers theme customization options such as colors, logos, and the ability to use a different theme for administrative tasks."

Modules can respond to each other by implementing
+a "hook".

Maybe more like 'By implementing 'hooks', modules can react to system events and further customize Drupal's behavior."

(basically, try and at least allude to what a hook is and why it's important, without going overboard)

Reading http://drupal.org/best-practices/do-not-hack-core, I'm not sure the quality of that page is really up to par with something that should be linked off to in README.txt. I wonder if we'd be better off here to just add a sentence like:

"Drupal's flexible architecture means that you should never need to 'hack core' (directly modify files that come with Drupal or one of its contributed projects) to achieve the custom functionality you want."

deviantintegral’s picture

A person trying to figure out "What is Drupal?" doesn't care about a "theming system" and how it "separates functionality and content." That's purely a developer distinction.

Perhaps not functionality, but separating appearance from content is a pretty important distinction. IME, that's a common reason for moving to a CMS in the first place. I think that's a pretty important idea for the README.

As for the don't-hack-core page, let's update that page directly. I actually think you're one-line makes a pretty good intro for that page.

mokko’s picture

Let's tackle the theming sentence first. I don't have a strong opinion with either alternative. I think deviantintegral has a point here: separation of functionality, content and appearance is often mentioned when reasoning about CMSs. But, of course, every solution vaguely comparable with Drupal offers this sepratation. Are there still people out there who write websites in a way where they don't separate appearance/functionality? Yes, certainly, but do we have to care about them when they already found the Drupal readme? Not sure.

#156 hints at possible configurations by listing most important options (activate one or more themes, customize theme features such as color), webchicks thinks that is too much information. Her suggestion is more concise:

"Drupal's appearance can be customized with the use of themes (extensions that control the fonts, colors, and layout of the site). Drupal offers theme customization options such as colors, logos, and the ability to use a different theme for administrative tasks."

deviantintegral is not objecting in general to this suggestion and only wants one aspect, the separation of functionality and appearance. The obvious compromise would be to take webchick's version and add the sepration of functionality and appearance.

Drupal contains a theming system to separate the appearance of your website from its functionality and content. Its appearance can be customized with the use of themes (extensions that control the fonts, colors, and layout of the site). Drupal offers theme customization options such as colors, logos, and the ability to use a different theme for administrative tasks.

Maybe a different style:

Drupal has a theming system which separates the appearance of the website from its functionality and content. The appearance can be customized by using themes (extensions that control the fonts, colors, and layout of the site). Aspects such as colors, logos can be changed and Drupal allows to use different themes for administrative tasks and for regular use.

Next the developing section: I find webchicks proposal better. Her sentence in context:

Drupal contains an extensive API that allows you to extend and modify the functionality of your site. By implementing 'hooks', modules can react to system events and further customize Drupal's behavior. Before you create your own module, try ...

Thridly, the link to the do-not-hack-core page: Not to link to that page would be less work, so I am in favor of it. If somebody wants to edit that best practice page, please go ahead. Then we can still keep that link; otherwise we take it out.

Not sure if it is worth it to update the path at this point. Let's see first if there is some fast reaction or cross post.

BTW: Thanks for the lessons on patches. I am learning.

webchick’s picture

I'm fine with both aspects of theming being listed there. I'm not fine with jumping into "the theming system" immediately, without first telling people what the heck a theme is, which is the actual pertinent piece of information to communicate here.

On "do not hack core," I think I'd prefer a general link to http://drupal.org/best-practices rather than calling specific attention to this one rule (in fact, the landing page there is actually quite good!). There are lots of things that are important to know going into Drupal, not hacking core is just one of them. I do think we should certainly mention not hacking core in the README.txt, but in the appropriate context, and along with the why. We are limited in the number of links we can put in here, and it seems odd to put so much attention on a single page that tells people "there are T-Shirts made with this phrase" (wtf?). And I don't really want to push off all the awesome work done on this patch to also bikeshed what the "Do not hack core" page in the handbook should say.

mokko’s picture

FileSize
3.18 KB

1) theme section: Themes are now explained, but used. The reference to theme developing in the appearance section is gone now. I think it confuses more at this point than it helps.
2) developing section changed according to #157 and #160.
-This includes includes the link to best practices in general. I noticed that best practices does not only refer to developing, but also to maintenance, but I think this is not a major problem.
-As per #157 we should say "don't hack core" in this paragraph, so I added a sentence and tried to be a little more terse to keep the paragraph to roughly the same length as before.

Now it's time for you again to comment.

PS: My emacs counts line length in columns beginning with 0. I am not sure now how long 80 characters are? Do you count the first as zero or 1? No answer on http://drupal.org/coding-standards. My eclipse starts with 1. I guess I am on the safe side when starting with 1.

jhodgdon’s picture

Status: Needs review » Needs work

You don't want to have more than 80 characters on a line, so if your editor starts counting at zero, you need to make sure you don't exceed column 79.

Also, just as a note, if you want to add an "interdiff" file, PLEASE name it something.txt rather than something.patch or something.diff, so it will be ignored by the testing bot

This patch needs a fix -- there is at least one spot where there is a space at the end of the line. I suggest if you are using emacs, you turn on the setting that highlights end of line whitespace with a bright red character. [the line I found is in the Appearance section]

This is also not grammatically/stylistically good:

 Drupal 
+lets you change aspects such as colors, logos, and you can choose different
+themes for administrative tasks and for regular use.

And the + sign in the middle of this line needs to be removed:

+architecture+means that you should never need to 'hack core' (directly modify
+ * Recommended best practices for coding and maintenance:

How about removing "recommended", since it's sort of implied by "best practices"?

Finally, is there an extra blank line at the end of the file? If so, please remove it.

marcvangend’s picture

I'm not completely happy with some of the recent changes in the appearance section. The first sentence should not be about separating the appearance from functionality and content, because it's not a goal on itself. The first sentence of a section should say that Drupal empowers you to do stuff, not explain the theory it is based upon.

The fact that you can create your own themes is important; I really think we should mention it.

How about this?

APPEARANCE
----------

Drupal allows you to customize the appearance by using themes (extensions that
control the fonts, colors, and layout of the site). A theme lets you change
aspects such as colors and logos, and you can choose different themes for
administrative tasks and for regular use. By separating the appearance from
functionality and content, Drupal allows you to control the look of the website
without changing the way it works. Themes are available for download, but you
can also create your own theme.

More about themes:
 * Download contributed themes to sites/all/themes to modify Drupal's
   appearance:
   http://drupal.org/project/themes
 * Developing themes:
   http://drupal.org/documentation/theme

Something else: I asked a client of mine (experienced web editor, no Drupal knowledge) to read this document (in the #145 version), just to see if all of this is as good as we hope it is. She told me that, in her opinion, the text is well written and clear (phew!) but she did wonder what kind of machine is needed to run "such a big program", as she put it. There is a link to drupal.org/requirements in INSTALL.txt, but perhaps we should link to it directly?

jhodgdon’s picture

I like the new Appearance section except:
- the appearance -> its appearance [first sentence]
- I think the 2nd sentence is partly a duplicate of the first? The version that I wrote of that sentence a while back I think said something about most themes giving you options so you can customize logos and colors without even getting a new theme, but the way it reads now, the bit about colors and logos sounds like it is just a duplicate of what was already said in the first sentence.
- but -> and [last sentence of first paragraph]

Regarding linking to the requirements doc... I'm not totally against it, but we do refer people to INSTALL.txt in this doc, so I think maybe that's enough?

Xano’s picture

This probably is just me late at night, but doesn't appearance already include concepts such as font and colours? Why explain what appearance means with such specific and yet limited terms?

mokko’s picture

I think that the suggestion from #163 reads much better. It is certianly an improvement. And everybody (#162-165) seems to agree that the appearance sections needs work. Should we just take that version or is something missing there? I can try to fix the last patch after I catch a few hours of sleep...

uNeedStuff’s picture

My suggestion for the Appearance Section. imho the simpler the better.
In Drupal the appearance of your site is set by the theme (extensions that
set the fonts, colors, and layout). A theme lets you easily change how your
site, including the content looks. Changing how the site looks does not effect
the actual content or visa versa. You can select multiple themes, change
themes, or customize a theme to create the style or appearance of your site.

More about themes:
* Download contributed themes to sites/all/themes to modify Drupal's
appearance:
http://drupal.org/project/themes
* Developing themes:
http://drupal.org/documentation/theme

mokko’s picture

I attempt to fuse both suggested versions, including exchanging the 'but' by 'and'. This is a new patch. Also I attach interdiff to show that I can. What about this?

mokko’s picture

Status: Needs work » Needs review

Let's see what testbot says this time.

webchick’s picture

Status: Needs review » Needs work
 A theme lets you easily change how your site,
+including the content looks. Changing how the site looks does not effect the
+actual content or visa versa.

That first sentence is awkward. I think because we need a comma after "content". Also, "effect" should be "affect."

But then I'm left wondering why we are spending so much time here talking about content; there's nothing "special" about this behaviour. It's exactly what you would expect a content management system to do. So why call special attention to it in README.txt?

If we're going to mention anything here, I'd say mentioning the layout is important and that each theme has its own layout and their own regions where their own blocks can be placed into. But of course, then you'd have to start talking about blocks, and this is already getting long enough. :P

 You can select multiple themes, change themes,
+or customize a theme to create the style or appearance of your site. Themes
+are available for download, and you can also create your own theme.

Once again, please remove mention of multiple themes in this file. The existence of multiple themes is a complete edge case, and we do nothing at all with them in core (beyond the fact that using an admin theme by necessity enables two themes). Mentioning the ability to change themes also seems unnecessary. Of course you can change themes.

+architecture+means 

"architecture means"

mokko’s picture

Status: Needs work » Needs review
FileSize
3.24 KB
1.83 KB

Sorry, I have no brain left anymore for actually reading that text. I try to apply, however, all the suggestions/corrections which I understand:
-content comma applied
-effect->affect
-content/appearance. Was already reduced to one single short sentence: "Changing how the site looks does not affect the
actual content or visa versa." Webchick doesn't like it, although I think it doesn't hurt. Take it out or leave it? Take it out, I guess. If anybody bothers enough, speak up now.
-I didn't replace this with anything since I don't quite get what webchick is hinting at or how to say it. If anybody else wants to give it a shot, this would be a good time. I currently don't think it is necessary.
-multiple themes removed. I think it stayed there so long only because of admin vs normal theme. This distinction is not made anymore, but I don't find it so relevant that it belongs in the README.txt.
-changing themes removed.
-architecture + fixed.

Thanks!

jhodgdon’s picture

FileSize
3.18 KB

Several minor issues with the patch in #171:
- Several lines had trailing whitespace.
- There was a which->that usage error in the Config section.
- I did quite a bit of paring and remodeling in the Appearance paragraph, as there was a lot of redundancy.
- Also in the Appearance section, "Developing themes" in the bullet list didn't match with "Download" (one is -ing and the other is imperative), so I changed it to "Develop your own theme".
- In the Developing section, two of the three bullet points were informational and one -ing, so I changed the first one to "Guide to module development" so they were more parallel, and the heading to "References for Drupal coding".
- There was an extra blank line at the end of the file.

Patch attached with the above changes.

mokko’s picture

Great! For me, it looks pretty good now.

Why does testbot not report any result? It seems to be finished as far as I can tell. Should we retest or continue to wait?

dww’s picture

Meta: who cares about the test bot at all in this issue? We're adding a READE.txt file, nothing more. It's inconceivable that we could introduce any bugs or test failures with this issue. Once everyone agrees on the exact wording and punctuation and whitespace, this is RTBC. The test bot is not helpful for this issue, and should be ignored.

marcvangend’s picture

Status: Needs review » Needs work

Great job all, I think we're almost there.
I have a couple of remarks about the 'Developing for Drupal' section.

+files that come with Drupal or one of its contributed projects) to achieve the
+custom functionality you want. Instead contribute to an existing module or

I think "custom" is redundant here. I don't know what it means in this context.

+custom functionality you want. Instead contribute to an existing module or
+write your own.

That last sentence came as a surprise to me. Basically, we're saying that contributing to an existing module is an alternative to hacking core. That sounds logical to us, but probably not to new Drupal developers. It assumes that the user searches for contrib modules before starting writing his own, that he actually finds a similar module to contribute to, and that the developer knows how contributing to an open source community works. I think we cannot make such assumptions. Let's bring back the sentence about searching before coding (a previous version read "Before you create your own module, try searching at http://drupal.org"). Maybe we can describe the different options in their chronological order:
0. Don't hack core/contrib.
1. Search for an existing module; if it works, use it.
2. If a module comes close, consider contributing.
3. If no module comes close, write your own.

jhodgdon’s picture

Status: Needs work » Needs review
FileSize
3.84 KB

dww: If you scroll up, you'll see that some of the past patches didn't pass because they were not properly formatted, so we might care just a slight bit about the tests. However, of course I'm sure my patch is fine. :)

Regarding #175 -- agreed... I've given the Developing section a complete rewrite, including the bullet list. The other sections are untouched since the last version.

mokko’s picture

I think this is great! I wonder if we want to link to

http://api.drupal.org/api/drupal/includes--module.inc/group/hooks/7

in the developer section. Probably not necessary, but maybe helpful.

On the other hand, there are already 5 links and that already seems maxium.

jhodgdon’s picture

I don't think that link is necessary. We already have a link to api.drupal.org in that section, and the module developer's guide page (which is also linked) immediately leads you to the Handbook section on the API, which is probably a better starting place for new developers than the reference section on hooks.

uNeedStuff’s picture

Everything reads very nicely and simply until you get to the 2nd paragraph of the Developing for Drupal. Previous paragraphs are written more as statements, and this enters into something sounding more like opinion and somewhat of a plead or a should type paragraph. I'd suggest:

Use Drupal community Modules first. When you have a need for additional functionality, search the community for a module. If what you find isn't an exact match consider patching a current module before writing a completely new one. Contributing back to the community.

Which to me suggests a best practice simply and points them back to the community.

jhodgdon’s picture

Hmmm... OK, I get the sentiment, but the paragraph you suggested needs some work...

How about this:

When you need new functionality for your Drupal site, begin by searching for an existing contributed module. If you find an exact match for what you need, use it. If you you find a module that matches except for a bug or an additional needed feature, patch the module and contribute your patch back to the project. Only create a new custom module if nothing you find comes close to what you need.

uNeedStuff’s picture

Better how about:
When you need new functionality for your Drupal site, search for existing contributed modules. If you find a module that matches except for a bug or an additional needed feature, patch the module and contribute your patch back to the project. Create new custom modules when nothing found comes close to what you need.

I think the using it would be implied so is unnecessary. Also rephrased to statements.

jhodgdon’s picture

FileSize
3.67 KB

OK, I think that's pretty good. Here's a new patch, with the above (except a slight change to the last sentence). Only the 2nd paragraph of the Developing section differs from the last patch in 176 above.

uNeedStuff’s picture

Looks good to me :)

marcvangend’s picture

FileSize
3.71 KB

I really like #182. Just one thing: I think that the word "patch" is jargon and it should be treated accordingly. My proposal:

If you find a module that matches except for a bug or an
additional needed feature, change the module and contribute your improvements
back to the project in the form of a 'patch'.

A new "patch" is attached :-)

uNeedStuff’s picture

I agree however, I think you should then leave the whole patch part off and just end the sentence after project. How they do all that will be covered elsewhere so just saying to do it in the readme is enough imho.

marcvangend’s picture

uNeedStuff: I deliberately wrote it like this because the word 'patch' is also used in the links below:

 * Contribute a patch:
   http://drupal.org/patch/submit

However we could also do this:

If you find a module that matches except for a bug or an
additional needed feature, change the module and contribute your improvements
back to the project.

combined with:

 * Contribute your code:
   http://drupal.org/patch/submit
mokko’s picture

I am not sure that I agree that "patch" is (too much) jargon in the first place. Is it too much too ask to deal with a word like this when you are reading the developing section of Drupal's README.txt? I find that difficult to say. Maybe yes, and thus I am ok with the square quotes although I am not sure they help.

I wouldn't take out the whole sentence, since in case I do not not know the term "patch" and search for it on d.o or wikipedia I find very useful pages. But we can take out "in the form of a 'patch'" since at this point it is not important how to contribute back.

I think what is special about Drupal compared to similar projects is that you shouldn't patch/modify core. And we clearly say this now.

What do the others think?

Criticial issues are disappearing rapidly today, looks like RC1 is about to manifest very soon...

uNeedStuff’s picture

I'm fine with it either way, what I feel is important is that a new user who may read the entire thing, not come away thinking I have no idea what anyone just said ;) I think the re-write has done that. I can't imagine not searching for what I don't understand, I do it all the time, however most people I work with wouldn't, not everyone heads off to search.

I don't think it's too much to ask, it's should we be asking.

If you want to leave the word in there then list it 1st, describing it 2nd.

If you find a module that matches except for a bug or an
additional needed feature, change the module and submit a 'patch' ,
contributing your improvements back to the project.

marcvangend’s picture

Mokko: at least I'm sure that I didn't know what a patch is when I started using Drupal. Just adding quotes may not help, but my proposal does more than that; it changes "patch the module and contribute your patch back to the project" to "change the module and contribute your improvements back to the project in the form of a 'patch'".

I really think the "in the form of a patch" part is helpful here. If you just tell people to contribute, that may raise a lot of questions. We cannot answer all of those questions here, but at least the word "patch" provides a good search term to start with.

mokko’s picture

Now I see. I think marcvangend's proposal is excellent. It mentions the term "patch" and the list links to http://drupal.org/patch/submit. In this context quote means something like "you don't need to understand the term 'patch' immediately", but that's what it's called and further information is available if you follow the link.

RTBC from my point of view

jhodgdon’s picture

I am fine with #184, except "patch" should be in double quotes rather than single quotes for standard American English usage (which is our standard for Drupal docs in general).

I don't think "patch" is actually jargon though. It is a standard term in software development circles. So I am also OK with leaving out the quotes, though I don't object to them.

webchick’s picture

Let's do double quotes. We don't know the background of the person reading this file, so might as well assume they don't know what a patch is. If they do know what a patch is, they'll understand it's being defined for the benefit of those who don't, methinks.

mokko’s picture

FileSize
3.71 KB

with double quotes. Otherwise unchanged.

mokko’s picture

One could read #192 as in favor for defining patch. I wonder if webchick actually means this or if she is fine with current compromise which is no formal explanation of patch inside README.txt, and yet we don't leave it unexplained since we provide a link to the corresponding d.o page. I think that's sufficient. Am i wrong?

EvanDonovan’s picture

Currently, 'hook' has single quotes but "patch" has double quotes. "Hook" should have double quotes for American English usage (presuming that's what we are going by?). "Patch" should either have double quotes as in the patch, or no quotes, since it's a more standard term.

However, further down in the file, "patch" has no quotes, as part of the phrase "Contribute a patch", so possibly the quotes should be removed for consistency's sake.

Other than that, I think this is RTBC.

jhodgdon’s picture

I think it's OK to not have quotes on patch in the bullet list. Hook should have double rather than single quotes.

jhodgdon’s picture

I'm glad we're down to quibbling about quotes. :)

EvanDonovan’s picture

Here's the new patch, brought to you courtesy of my new best friend, cvs fakeadd: http://wimleers.com/blog/cvs-diff-new-files-fakeadd

Same as #193, other than changing "hook" to use double rather than single quotes, for consistency. Should be RTBC.

EvanDonovan’s picture

FileSize
3.71 KB

Attached here, sorry :)

mokko’s picture

FileSize
3.71 KB

SORRY CROSS POSTING! As far as I can tell patch from above and this one should be identical!

Me, too! And Thanks for that excellent proof reading!

I changed the single quotes in hooks to double quotes and left the patch in double.

In my understanding, it is fine if we emphasize the first use of "patch", but not the 2nd. These are not the kind of quotes that indicate "so-called". These are actually hooks and actually patches, not a so-called hook and a so-called patch. By putting the quotes, we only signal that it is a technical term which we do not ask everybody to know. This is at least how I understand it.

deviantintegral’s picture

FileSize
3.61 KB

This looks very good to me. There is one sentence that I'm having trouble with when I read it aloud:

The API consists of "hooks", which allow modules to react to system events and customize Drupal's behavior, and functions that standardize common operations such as database queries and form generation.

I think the problem is the order of database queries and form generation. I'm assuming "database queries" refers to "functions", and "form generation" refers to "hooks". If I test by remove the middle clause, I think the following makes more sense:

The API consists of "hooks" and functions that standardize common operations such as form generation and database queries.

Here's a patch with only that change. Everything else looks RTBC to me (though I'll verify all of the links in a minute).

deviantintegral’s picture

FileSize
3.61 KB

The best-practices URL had a trailing slash in it, unlike all of the other URLs. Fixed in the attached patch.

I verified all of the URLs and they all go to the expected pages.

EvanDonovan’s picture

@deviantintegral: I think that your change modifies the meaning of the sentence, making it factually incorrect. The sentence is intending to indicate the difference between what Drupal hooks & API functions generally do.

I think that #200 is RTBC, apart from the trailing slash issue.

Can #200 be re-rolled with the trailing slash change from #202, and then we can consider this done?

marcvangend’s picture

FileSize
3.71 KB

EvanDonovan: I agree. Here is the patch from #200 without the trailing slash.

I really can't think of anything left to do. I can hardly believe the amount of work that has been done here, how many different versions we have seen, and how different this patch is from the one in #1... LOL, I even thought this was RTBC more than a year ago :-) Well done everyone!

EvanDonovan’s picture

Status: Needs review » Reviewed & tested by the community

Good to go :)

deviantintegral’s picture

Agreed. #204 looks good to me.

jhodgdon’s picture

Agreed on #204. I just read it through once more and I think it's all flowing nicely.

mokko’s picture

Good to go! Yay!

webchick’s picture

Status: Reviewed & tested by the community » Fixed

GREAT job on this, folks!! Awesome, awesome collaboration effort here.

Read it over again once more and looks great here, too.

Committed to HEAD. :D Thanks!!

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.