Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
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.
Comment | File | Size | Author |
---|---|---|---|
#204 | 607028-204.patch | 3.71 KB | marcvangend |
#202 | 607028.202-README.patch | 3.61 KB | deviantintegral |
#201 | 607028.201-README.patch | 3.61 KB | deviantintegral |
#200 | 607028-198.patch | 3.71 KB | mokko |
#199 | drupal_607028-198.patch | 3.71 KB | EvanDonovan |
Comments
Comment #1
cweagansWoo! 278k patch engage!
Comment #3
cweagansThis one actually applies >.<
Comment #5
cweagansThey pass locally....let's give that another go.
Comment #6
moshe weitzman CreditAttribution: moshe weitzman commentedFor 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.
Comment #7
deviantintegral CreditAttribution: deviantintegral commentedWhy not just have a README.txt or DEVELOPER.txt with this sort of information?
Comment #8
sunComment #9
webchickI 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?
Comment #11
webchickCross-posted. Adjusting title.
Comment #12
webchickTo 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.
Comment #13
deviantintegral CreditAttribution: deviantintegral commentedI 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.
Comment #14
deviantintegral CreditAttribution: deviantintegral commentedComment #16
cweagansDeviantIntegral, see my patch above. It contains the link ~4000 times ;)
Comment #17
deviantintegral CreditAttribution: deviantintegral commentedThanks - 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?
Comment #18
webchickWeird. 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.
Comment #19
sunThis will solve it.
Comment #20
jhodgdonA 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.]
Comment #21
tgeller CreditAttribution: tgeller commentedI've taken the liberty of making it more concise. Use or toss these edits as you like -- no love lost.
Comment #22
tgeller CreditAttribution: tgeller commentedI've taken the liberty of making it more concise. Use or toss these edits as you like -- no love lost.
Comment #23
webchickRe-titling issue. This is about more than developers now (and that's a good thing!)
Comment #24
jhodgdonI 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.
Comment #25
winston CreditAttribution: winston commentedWell, 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.
Comment #26
marcvangendI 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.
Comment #27
jhodgdonI like the task-oriented headers of #26. Still not sure about concise vs. wordy. Several comments in #20 still apply to the latest patch.
Comment #28
uNeedStuff CreditAttribution: uNeedStuff commentedI 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.
Comment #29
marcvangendI 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.
Comment #30
codeknitter CreditAttribution: codeknitter commentedI 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.
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.
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.
Comment #31
deviantintegral CreditAttribution: deviantintegral commentedI'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:
Comment #32
marcvangend@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.)
Comment #33
jhodgdonHey marcvangend: Asking 1 person is better than asking no people, or those of us who are "experts" speculating! :)
Comment #34
deviantintegral CreditAttribution: deviantintegral commentedIndeed - thanks marcvangend.
I've made the following edits:
Comment #35
marcvangendThanks 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:
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?
Comment #36
marcvangendOuch, forgot the attachment.
Comment #37
marcvangend...and here is one more for consistency (just one extra blank line)
Comment #38
deviantintegral CreditAttribution: deviantintegral commentedI 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.
Comment #39
jhodgdonThe version in #38 is pretty close... A few suggestions:
a) In the "look and feel" section, how about adding this link: http://drupal.org/theme-guide -- I think it is a better place to start than http://api.drupal.org/api/group/themeable/7, but at least it should be an additional link.
b) In the "write code" section:
I think this would be better as two separate bullet points:
c) Also in "write code":
Minor suggested change:
d) Add http://drupal.org/node/326 to the links in the API bullet point. Or better yet, combine the current API and hooks bullet points into:
Comment #40
deviantintegral CreditAttribution: deviantintegral commentedHere is an update implementing all of the suggestions in in #39.
Comment #41
jhodgdonI like #40. Maybe some of the other reviewers should chime in before we mark it RTBC though?
Comment #42
marcvangend#40 looks good. RTBC AFAIC.
Comment #43
webchickErm. :) Joining the community has nothing to do with configuring your site. http://drupal.org/handbook/customization seems like an obvious thing to link to here.
Sorry, but we are not linking to anything with "5" in the URL from Drupal 7's README.txt. We should either create the pages in the proper place, or do as api.drupal.org does and make a single URL that always points to the most current data.
Also, I appreciate terseness, but these descriptions feel a bit overly terse. People who already know what they're doing aren't going to bother reading this document. This document is for the person who just downloaded Drupal for the first time and wants to know what's up. And currently, they need to click every single link in here to know if they need to read it or not. (which, of course, they won't.)
An example of going from "super terse" to "reasonably terse" might be changing a section like:
to something like:
The text there I'm sure needs some love, but that's about the level of terseness I was going for. Think "Paragraph overview about whatever to give me the gist, followed by links to external resources with more details, each accompanied with a one-sentence description to help me decide if i should click it."
Comment #44
jhodgdonSounds like that's a "needs work" from webchick...
Comment #45
deviantintegral CreditAttribution: deviantintegral commentedHere's an update that:
I've attached a diff from #40 as well in case that helps anyone to review.
Comment #46
XanoJust a short brain fart: nobody ever reads readme files. What about a (hook_)help page?
Comment #47
marcvangendThere 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://".
Comment #48
jhodgdonI'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.
Comment #49
deviantintegral CreditAttribution: deviantintegral commentedHere's an update which:
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?
Comment #50
dwwNow 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...
Comment #51
marcvangendI 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.
Comment #52
jhodgdonRegarding 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:
should also be in the "CHANGE THE LOOK AND FEEL OF YOUR DRUPAL SITE" section.
Comment #53
deviantintegral CreditAttribution: deviantintegral commentedHere's an update that:
Comment #54
uNeedStuff CreditAttribution: uNeedStuff commentedI'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.
Comment #55
deviantintegral CreditAttribution: deviantintegral commentedThe attachment in #54 has a few typography issues:
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.
Comment #56
webchickYeah, 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.
Comment #57
deviantintegral CreditAttribution: deviantintegral commentedI 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.
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?
Comment #58
uNeedStuff CreditAttribution: uNeedStuff commentedHere 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.
Comment #59
deviantintegral CreditAttribution: deviantintegral commentedReview notes:
come back?
Comment #60
uNeedStuff CreditAttribution: uNeedStuff commentedIf 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.
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.
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
Comment #61
deviantintegral CreditAttribution: deviantintegral commented@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.
Comment #62
dwwI'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...
Comment #63
deviantintegral CreditAttribution: deviantintegral commentedHere is a version fixing only typography issues from #60; I'll post a review of the content in the moment.
Comment #64
deviantintegral CreditAttribution: deviantintegral commentedThis is based off of a comparison of the version from #57:
Comment #65
uNeedStuff CreditAttribution: uNeedStuff commentedHow 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.
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
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.
Comment #66
deviantintegral CreditAttribution: deviantintegral commentedHere'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!
Comment #67
uNeedStuff CreditAttribution: uNeedStuff commentedLooks 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.
Comment #68
sepeck CreditAttribution: sepeck commentedremoved version specific # in two urls per request of jhodghon
Comment #69
jhodgdonThanks! 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
Comment #70
deviantintegral CreditAttribution: deviantintegral commentedGreat - 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.
Comment #71
drifter CreditAttribution: drifter commentedLooking good, here's a patch rolled with the #70 version.
Comment #72
drifter CreditAttribution: drifter commentedNo discussion for a few days now, but it has been well discussed and edited, so, marking as RTBC?
Comment #73
deviantintegral CreditAttribution: deviantintegral commentedWe're still waiting on a D7 equivalent for the documentation for http://drupal.org/getting-started/6/admin/build/themes.
Comment #74
jhodgdonRe #73: Do we need just a stub, or do we need the whole section to be built?
Comment #75
jhodgdonI don't think we're ready to build the entire page yet, but here's a stub page on Drupal themes:
http://drupal.org/node/637480
Someone with URL alias permissions could make a URL alias. I suggest
site-building/themes
And by the way, I suggest revising the patch slightly. It currently says:
How about:
There is also still one more bad link in the README patch #71, in the bottom section:
http://drupal.org/getting-started/5/install-contrib/modules
That should be:
http://drupal.org/getting-started/install-contrib/modules
Comment #76
Damien Tournoud CreditAttribution: Damien Tournoud commentedIt 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).
Comment #77
jhodgdonHow about the license too?
Comment #78
deviantintegral CreditAttribution: deviantintegral commentedHere is a patch which:
Comment #79
deviantintegral CreditAttribution: deviantintegral commentedComment #80
jhodgdonOh 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?
Comment #81
jhodgdonI just sent LeeHunter a message asking if he could comment here on better links/organization for the top section of the Readme.
Comment #82
LeeHunter CreditAttribution: LeeHunter commentedI 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.
Comment #83
webchickHm. 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/?"
Comment #84
deviantintegral CreditAttribution: deviantintegral commentedHow 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?
Comment #85
deviantintegral CreditAttribution: deviantintegral commentedSee #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.
Comment #86
frankcarey CreditAttribution: frankcarey commentedI 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.
Comment #87
frankcarey CreditAttribution: frankcarey commentedAlso, 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.
Comment #88
frankcarey CreditAttribution: frankcarey commentedRobLoach's Unspoken Rules of Drupal: pretty succinct :) http://robloach.net/node/128
Comment #89
mcrittenden CreditAttribution: mcrittenden commentedSub.
Comment #90
marcvangendWow, 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.)
Comment #91
deviantintegral CreditAttribution: deviantintegral commentedThe attached patch:
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:
Comment #92
deviantintegral CreditAttribution: deviantintegral commentedThis is no longer really a "quick fix" :)
Comment #93
marcvangendI 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/.
Comment #94
webchickThat 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.
Comment #95
marcvangendSame patch as in #91, now links to http://api.drupal.org/api/drupal/7 instead of http://api.drupal.org/.
Comment #96
XanoThis is a short review focused on writing style and usability.
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.
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.
I'm no native speaker of English, but shouldn't this be "Download contributed modules to (...)"?
* 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.
Comment #97
xmacinfoAs per Xano comments, changing the status.
Adding a README.txt is welcome. I like the content and the layout.
Comment #98
marcvangendXano, 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.
Comment #99
Eric_A CreditAttribution: Eric_A commentedApparently the bot does not care, but
You must not add a space between $Id and $ when you commit the keyword for the first time.
Comment #100
XanoGood 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
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:
* 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.
Comment #101
marcvangendXano: 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.
Comment #102
Xano* 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.
Comment #103
XanoI forgot to set the status.
Comment #104
marcvangendBart, that's the wrong patch :-D
Comment #105
XanoI suck at adding new files to patches. Here's the entire README.txt from #102.
I also fixed the
$Id$
mentioned in #99.Comment #106
jhodgdonReviewing the readme attached in #105:
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.
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.
d) which -> that
e) Again, needs a line ending in a : before the list that follows this paragraph.
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"?
Comment #107
Xanob) 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.
Comment #108
jhodgdonI'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.
Comment #109
sepeck CreditAttribution: sepeck commented@91 - alias added. let me know if you want it to be different.
http://drupal.org/best-practices/do-not-hack-core
Comment #110
Xano* 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.
Comment #111
deviantintegral CreditAttribution: deviantintegral commentedI agree with "To further...", so I've changed that in the attached patch.
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.
Comment #113
marcvangend(overriding testbot)
Comment #114
jhodgdonOK, here's another review:
a)
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)
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)
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)
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)
Needs to be followed by :
Comment #115
joachim CreditAttribution: joachim commentedOverall 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."
Comment #116
jhodgdonPlease 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.
Comment #117
jhodgdonI also just noticed the proposal above has some trailing whitespace at ends of lines. Anyway, I'm making a new version...
Comment #118
jhodgdonHere's a new patch... (and removing the documentation tag - this is in the documentation component, the tag is not necessary).
Comment #119
joachim CreditAttribution: joachim commentedJust nitpicking now ... ;)
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.
Should we have a matching bit for modules?
And should we have a links list for the themes bit too?
Powered by Dreditor.
Comment #120
jhodgdona) 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?
Comment #121
joachim CreditAttribution: joachim commented> 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.
Comment #122
jhodgdonThe section about writing your own code has a link to the theming guide.
Comment #123
joachim CreditAttribution: joachim commentedOkay, '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 :/
Comment #124
sunFWIW, "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.
Comment #125
jhodgdonOK, here's a new patch.
Comment #126
jhodgdonoops, 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...)
Comment #127
XanoWhere'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.
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.
Not only core's functionality can be modified and overriden, but contrib's as well.
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.
Comment #128
jhodgdonI 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".
Comment #129
XanoI 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.
Comment #130
jhodgdonWell, 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.
Comment #131
XanoThe 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:
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"?
"Custom modules and themes"
"CSS rules" is a more common term, I believe.
"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.
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"?
"Custom modules and themes"
"CSS rules" is a more common term, I believe.
"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.
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.
Comment #132
jhodgdonOK. 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).
Comment #133
joachim CreditAttribution: joachim commented> 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.
Comment #134
jhodgdonHere's a new patch. I think all of the concerns expressed since the last patch have been addressed. Hopefully. :)
Comment #135
jhodgdonWhoops, hadn't quite saved my latest version. Here's the same patch, minus one comma.
Comment #136
joachim CreditAttribution: joachim commentedLooks good to me! :D
Comment #137
webchickWow, GREAT work on this, all! This has evolved quite a bit since the last time I looked at it.
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:
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.
Comment #138
marcvangendI 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.
Comment #139
marcvangendComment #140
joachim CreditAttribution: joachim commentedLooks 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.
Comment #141
mokko CreditAttribution: mokko commentedIn 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.
Comment #142
mokko CreditAttribution: mokko commentedI 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?
Comment #144
joachim CreditAttribution: joachim commentedBot is on crack today. RTBC from me.
Perhaps let jhodgdon give final approval :)
Comment #145
marcvangend#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.
Comment #146
cweagansCouple more changes:
Can we say "configurable options" here? I think it better communicates what you're trying to say here.
New Drupal user says: "Available for download where?"
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."
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.
Comment #147
marcvangendI 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.
The link to the download page is in the bulleted list right below that sentence. Isn't that good enough?
Comment #148
jhodgdonRE #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.
Comment #149
mokko CreditAttribution: mokko commentedI 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
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:
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.
Comment #150
mokko CreditAttribution: mokko commentedThis 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?
Comment #151
mokko CreditAttribution: mokko commentedI guess I need to change the status to find out what the testbot thinks.
Comment #153
dww@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.
Comment #154
mokko CreditAttribution: mokko commentedyes. 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?
Comment #155
deviantintegral CreditAttribution: deviantintegral commentedThe patch in #150 is missing a blank line, confusing patch. Will upload a new file shortly.
Comment #156
deviantintegral CreditAttribution: deviantintegral commentedHere's a patch that:
Comment #157
webchickThis is looking really good. A couple more small nit-picks:
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."
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."
Comment #158
deviantintegral CreditAttribution: deviantintegral commentedPerhaps 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.
Comment #159
mokko CreditAttribution: mokko commentedLet'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:
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.
Maybe a different style:
Next the developing section: I find webchicks proposal better. Her sentence in context:
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.
Comment #160
webchickI'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.
Comment #161
mokko CreditAttribution: mokko commented1) 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.
Comment #162
jhodgdonYou 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:
And the + sign in the middle of this line needs to be removed:
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.
Comment #163
marcvangendI'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?
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?
Comment #164
jhodgdonI 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?
Comment #165
XanoThis 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?
Comment #166
mokko CreditAttribution: mokko commentedI 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...
Comment #167
uNeedStuff CreditAttribution: uNeedStuff commentedMy 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
Comment #168
mokko CreditAttribution: mokko commentedI 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?
Comment #169
mokko CreditAttribution: mokko commentedLet's see what testbot says this time.
Comment #170
webchickThat 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
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"
Comment #171
mokko CreditAttribution: mokko commentedSorry, 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!
Comment #172
jhodgdonSeveral 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.
Comment #173
mokko CreditAttribution: mokko commentedGreat! 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?
Comment #174
dwwMeta: 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.
Comment #175
marcvangendGreat job all, I think we're almost there.
I have a couple of remarks about the 'Developing for Drupal' section.
I think "custom" is redundant here. I don't know what it means in this context.
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.
Comment #176
jhodgdondww: 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.
Comment #177
mokko CreditAttribution: mokko commentedI 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.
Comment #178
jhodgdonI 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.
Comment #179
uNeedStuff CreditAttribution: uNeedStuff commentedEverything 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.
Comment #180
jhodgdonHmmm... 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.
Comment #181
uNeedStuff CreditAttribution: uNeedStuff commentedBetter 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.
Comment #182
jhodgdonOK, 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.
Comment #183
uNeedStuff CreditAttribution: uNeedStuff commentedLooks good to me :)
Comment #184
marcvangendI really like #182. Just one thing: I think that the word "patch" is jargon and it should be treated accordingly. My proposal:
A new "patch" is attached :-)
Comment #185
uNeedStuff CreditAttribution: uNeedStuff commentedI 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.
Comment #186
marcvangenduNeedStuff: I deliberately wrote it like this because the word 'patch' is also used in the links below:
However we could also do this:
combined with:
Comment #187
mokko CreditAttribution: mokko commentedI 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...
Comment #188
uNeedStuff CreditAttribution: uNeedStuff commentedI'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.
Comment #189
marcvangendMokko: 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.
Comment #190
mokko CreditAttribution: mokko commentedNow 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
Comment #191
jhodgdonI 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.
Comment #192
webchickLet'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.
Comment #193
mokko CreditAttribution: mokko commentedwith double quotes. Otherwise unchanged.
Comment #194
mokko CreditAttribution: mokko commentedOne 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?
Comment #195
EvanDonovan CreditAttribution: EvanDonovan commentedCurrently, '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.
Comment #196
jhodgdonI think it's OK to not have quotes on patch in the bullet list. Hook should have double rather than single quotes.
Comment #197
jhodgdonI'm glad we're down to quibbling about quotes. :)
Comment #198
EvanDonovan CreditAttribution: EvanDonovan commentedHere'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.
Comment #199
EvanDonovan CreditAttribution: EvanDonovan commentedAttached here, sorry :)
Comment #200
mokko CreditAttribution: mokko commentedSORRY 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.
Comment #201
deviantintegral CreditAttribution: deviantintegral commentedThis looks very good to me. There is one sentence that I'm having trouble with when I read it aloud:
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:
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).
Comment #202
deviantintegral CreditAttribution: deviantintegral commentedThe 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.
Comment #203
EvanDonovan CreditAttribution: EvanDonovan commented@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?
Comment #204
marcvangendEvanDonovan: 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!
Comment #205
EvanDonovan CreditAttribution: EvanDonovan commentedGood to go :)
Comment #206
deviantintegral CreditAttribution: deviantintegral commentedAgreed. #204 looks good to me.
Comment #207
jhodgdonAgreed on #204. I just read it through once more and I think it's all flowing nicely.
Comment #208
mokko CreditAttribution: mokko commentedGood to go! Yay!
Comment #209
webchickGREAT 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!!