I recently looked through the entire list of contrib modules and there's some cleanup needed. * Shorter teasers so the download page isn't so huge * Some modules still need tagging * Modules that are similar could use "See also's" * Also, there are a lot of modules that aren't documented in the handbook A thread on the support list went a bit off topic and I asked there what module maintainers think of having someone changing their project pages. I got one response that the maintainer would like to be notified first. I decided to put this on the dev list and start a new topic to get more thoughts on this. If you maintain modules and have a bit of time (yeah, right, eh? ;) could you take a look at your modules and see if the project pages could use a little work? If you don't have the time, do you object to someone else doing it? I'm willing to email maintainers before touching their pages if that's what's wanted. I also could use some help with this project. I've been saying I'm going to do it for over a week and haven't done it. Good intentions and all that... :) If someone wants to help, we could each tackle a part of the alphabet and then it wouldn't be such a daunting task. I'm also looking for any review/comparisons between modules to add to the handbook. If you've had to decide between similar modules and are able to write up your decision making progress, let me know. Thanks, Michelle PS: Do you think this should be crossposted to the doc list? It is doc-oriented, but I needed to put it where maintainers would see it. I don't like crossposting unless people think it's warranted.
Michelle Cox wrote:
I recently looked through the entire list of contrib modules and there's some cleanup needed.
* Shorter teasers so the download page isn't so huge * Some modules still need tagging * Modules that are similar could use "See also's" * Also, there are a lot of modules that aren't documented in the handbook
i think it is within the spirit for site maintainers to improve project descriptions as they see fit, and without prior approval from module maintainers. an after the fact email like: 'i fixed your stink' is sufficient. maintainer could always edit again if needed. As an aside (i.e. lets not sidetrack this thread), one of the original visions of the new .info files is that their names and descriptions will be used by drupal.org project module. Thats one of the reasons we chose plain text .ini instead of PHP. I like reuse of .info files because it centralizes project metadata. We probably need some more metadata fields.
On 10/25/06 2:13 PM, Moshe Weitzman wrote:
Michelle Cox wrote:
I recently looked through the entire list of contrib modules and there's some cleanup needed.
* Shorter teasers so the download page isn't so huge * Some modules still need tagging * Modules that are similar could use "See also's" * Also, there are a lot of modules that aren't documented in the handbook
i think it is within the spirit for site maintainers to improve project descriptions as they see fit, and without prior approval from module maintainers. an after the fact email like: 'i fixed your stink' is sufficient. maintainer could always edit again if needed.
+1. Please :)
As an aside (i.e. lets not sidetrack this thread), one of the original visions of the new .info files is that their names and descriptions will be used by drupal.org project module. Thats one of the reasons we chose plain text .ini instead of PHP. I like reuse of .info files because it centralizes project metadata. We probably need some more metadata fields.
and also +1 -- James Walker :: http://walkah.net/ :: xmpp:walkah@walkah.net
How about a template for contributed modules? This can be something linked to from the node/add/project page, so people can use a fill in the blanks thing. This would make the projects look consistent and useful information would always be there.
There is already a template, the node form. It has several fields to fill in. If you advocate more structured information to be collected, IMHO it is not a good idea to collect them in the form of a free text template. But I can't think of a good template which would fit a reasonable amount of modules... Gabor Khalid B wrote:
How about a template for contributed modules? This can be something linked to from the node/add/project page, so people can use a fill in the blanks thing.
This would make the projects look consistent and useful information would always be there.
James Walker wrote:
i think it is within the spirit for site maintainers to improve project descriptions as they see fit, and without prior approval from module maintainers. an after the fact email like: 'i fixed your stink' is sufficient. maintainer could always edit again if needed.
+1. Please :)
As an aside (i.e. lets not sidetrack this thread), one of the original visions of the new .info files is that their names and descriptions will be used by drupal.org project module. Thats one of the reasons we chose plain text .ini instead of PHP. I like reuse of .info files because it centralizes project metadata. We probably need some more metadata fields.
and also +1
This is fine, but the last time I had someone 'correct' something for me, they didn't understand what I was doing and got it wrong. So there's something to be said for at least acknowledging the module maintainer here.
James Walker wrote:
i think it is within the spirit for site maintainers to improve project descriptions as they see fit, and without prior approval from module maintainers. an after the fact email like: 'i fixed your stink' is sufficient. maintainer could always edit again if needed.
+1. Please :)
"Earl Miles" wrote:
This is fine, but the last time I had someone 'correct' something for me, they didn't understand what I was doing and got it wrong. So there's something to be said for at least acknowledging the module maintainer here.
Well, there are coders, their are docs writers, their are marketing folks, their are project leaders, and so on. Each must communicate openly with the others, granted. But there is nothing wrong with flat-out saying: Some folks make a great module but can't write a description of how to use it that's worth the time it takes to read it. Nor should they feel bad because of such. I don't think the chemist who invented shampoo is the same person who crafted the perfectly expressed: Wet hair. Lather. Rinse. Repeat. This is way better than the original bottle text: Saturate the protein strands of the head with H20. Apply approximately 1 ml of our glycerin-based fat derivative to the palm of the hand. Increase the kinetic energy of the molecules surrounding the cranium through the application of friction, rotational spin and torque -- best done by rubbing the hand around and over the cranium at a nominal velocity with enough force to keep the palm in contact with the cranium. As the kinetic energy increases, the fats suspended in the glyercin-based mixture will begin to break down and absorb oxygen. This will produce a lather of mostly air. The free electrons produced by the added force and chemical breakdown will cause particles of dirt, dead skin cells, oils and air-based pollutants to break free from their weakly charged bond with the protein strands and remain suspended and electrically bound in the fatty lather. Rinse the entire head with warm water to remove the broken-down fatty lather, thereby rinsing away the now-bonded undesirable molecules. Repeat. They're both a swell read, but one is better for the end user. ;) Your point about involving the maintainer is well-said and well-heard. No one can really document a thing they don't understand, and the only way to know if they got it right is the maintainer to have some input in the revision. It seems like Michelle is making this point really clear, and it's good that maintainers are interested in the documentation and explanation of their work -- I think it will work out for everyone's benefit. -- inkfree
"Moshe Weitzman" wrote:
I like reuse of .info files because it centralizes project metadata. We probably need some more metadata fields.
An excellent point. (One file to rule them all. One file to bind them.)[*] The problem is: Out of 354 modules just checked, only _3_ use this file at all: refresh.info kml.info georss.info So, there's that. The general guideline of including an "INSTALL.txt", "README.txt" and "LICENSE.txt" is a very wobbly guideline also. Some have only the last, some have a README.txt which has only one sentence, saying "See some other document named blah" or similar. And some have files named without any extension at all [README]. A common, required and re-usable system should be able to avoid some of the call for a "Golden Seal" stamped onto some modules, indicating their level of quality. (I _still_ think that's a worthy system, but that debate was long and generally a non-starter.) -- inkfree [*] Plain text format with metadata labels (as it is) is excellent and re-usable in lots of ways. This should be taken advantage of, of course. I agree that there need to be more "label =" metadata data fields. Everthing should be here, and then it can be used to auto-generate the module description pages. Even whole "Module Library" descriptions could be downloaded in XML, for browsing descriptions. Yes, one well-formed file should be the basis of everything else -- maintainers only need to keep one ".info" source and that's it.
inkfree press wrote:
"Moshe Weitzman" wrote:
I like reuse of .info files because it centralizes project metadata. We probably need some more metadata fields.
An excellent point. (One file to rule them all. One file to bind them.)[*]
The problem is: Out of 354 modules just checked, only _3_ use this file at all:
refresh.info kml.info georss.info
There must be a problem with your search; many more modules than that have .info files already. At the very least views and panels have .info files in the TRUNK version (though not in 4.7 because they are not needed in 4.7)
On Wednesday 25 October 2006 23:13, Earl Miles wrote:
inkfree press wrote:
"Moshe Weitzman" wrote:
I like reuse of .info files because it centralizes project metadata. We probably need some more metadata fields.
An excellent point. (One file to rule them all. One file to bind them.)[*]
The problem is: Out of 354 modules just checked, only _3_ use this file at all:
refresh.info kml.info georss.info
There must be a problem with your search; many more modules than that have .info files already. At the very least views and panels have .info files in the TRUNK version (though not in 4.7 because they are not needed in 4.7)
Hi, a quick search in the contributions/modules/ directory (current CVS trunk checkout) gives the following results: contributions/modules$ find -name "*\.module" | wc -l 1159 contributions/modules$ find -name "*\.info" | wc -l 169 Regards, Tobias -- Tobias Toedter | Your lucky number is 3562364958674928. Hamburg, Germany | Watch for it everywhere.
"Tobias Toedter" wrote:
The problem is: Out of 354 modules just checked, only _3_ use this file at all:
refresh.info kml.info georss.info
There must be a problem with your search
Nope. I have a folder full of 4.7.x downloaded modules, and that's what I searched. I have no idea what's in CVS. I'm talking about what users get if they download a module: only 3 have such a file. -- inkfree
On Oct 25, 2006, at 5:23 PM, inkfree press wrote:
Nope.
I have a folder full of 4.7.x downloaded modules, and that's what I searched. I have no idea what's in CVS. I'm talking about what users get if they download a module: only 3 have such a file.
this is obviously wrong. those 3 .info files (in 4.7.x) are clearly a mistake, since the .info files don't mean anything to drupal 4.7.x core. a) the maintainers of those 3 modules didn't know what they were doing, and b) you don't understand what you're really looking for. you need to (as tobias has already done) count the .info files in the DRUPAL-5 or HEAD branches of the contrib repository, since those are the only places where maintainers *should* add the .info files. make sense? cheers, -derek (dww)
"Derek Wright" wrote:
b) you don't understand what you're really looking for.
Well, I think that understand perfectly what I was really looking for: I was looking for module directories for files with the extension ".info". Now, what I think you meant to use as your attempted insult was: "You don't know where to look." In that case, your rudeness respects reality. I have not looked in CVS, nor was I attempting to do so. :)~ -- inkfree "Civility is free."
The implication is valid though - how would the correct .info file be determined for purposes of display on the project page? If you use the default release authors will have to update releases just to change the project description. Using HEAD is inaccurate if its functionality differs significantly from that of the default release - the .info files and the project page should independently be able to reflect these differences. I don't see the benefit to merging these two descriptions given that they have different purposes. Back to the original topic, I recommend that any project description revisions be conducted as informal "reviews" that are posted to the module's issue queue and can then be accepted, rejected, or modified by the maintainer. This preserves the contributors' autonomy while encouraging quality improvements. I do agree that the module descriptions are often of poor quality. Guidelines or best practices in module descriptions, via http://drupal.org/node/7765, would also help without forcing changes upon maintainers. .ck Derek Wright wrote:
On Oct 25, 2006, at 5:23 PM, inkfree press wrote:
Nope.
I have a folder full of 4.7.x downloaded modules, and that's what I searched. I have no idea what's in CVS. I'm talking about what users get if they download a module: only 3 have such a file.
this is obviously wrong. those 3 .info files (in 4.7.x) are clearly a mistake, since the .info files don't mean anything to drupal 4.7.x core. a) the maintainers of those 3 modules didn't know what they were doing, and b) you don't understand what you're really looking for.
you need to (as tobias has already done) count the .info files in the DRUPAL-5 or HEAD branches of the contrib repository, since those are the only places where maintainers *should* add the .info files.
make sense?
cheers, -derek (dww)
Back to the original topic, I recommend that any project description revisions be conducted as informal "reviews" that are posted to the module's issue queue and can then be accepted, rejected, or modified by the maintainer. This preserves the contributors' autonomy while encouraging quality improvements. I do agree that the module descriptions are often of poor quality.
michelle and friends are *volunteering* to *improve our site* with *more accurate project descriptions*. the process above is cumbersome and almost guarantees that almost few descriptions get changed. less friction please.
On Oct 25, 2006, at 7:06 PM, Moshe Weitzman wrote:
Back to the original topic, I recommend that any project description revisions be conducted as informal "reviews" that are posted to the module's issue queue and can then be accepted, rejected, or modified by the maintainer. This preserves the contributors' autonomy while encouraging quality improvements. I do agree that the module descriptions are often of poor quality.
michelle and friends are *volunteering* to *improve our site* with *more accurate project descriptions*. the process above is cumbersome and almost guarantees that almost few descriptions get changed. less friction please.
Seconded. +1 Jonathan
On 10/25/06, Moshe Weitzman <weitzman@tejasa.com> wrote:
Back to the original topic, I recommend that any project description revisions be conducted as informal "reviews" that are posted to the module's issue queue and can then be accepted, rejected, or modified by the maintainer. This preserves the contributors' autonomy while encouraging quality improvements. I do agree that the module descriptions are often of poor quality.
michelle and friends are *volunteering* to *improve our site* with *more accurate project descriptions*. the process above is cumbersome and almost guarantees that almost few descriptions get changed. less friction please.
Michelle, we may as well take this back to documentation. Myself and Kieran have done this over time, generally without pre-notifying maintainers, etc.. e.g. look at Event, which has manual links to dependent modules, etc. Although, looking at it, I took out the "recommended" link to flexinode...and replace it to one for CCK. If it doesn't involve issues, it's usually best to keep it off the dev list :P -- Boris Mann
inkfree press wrote:
I have a folder full of 4.7.x downloaded modules, and that's what I searched. I have no idea what's in CVS. I'm talking about what users get if they download a module: only 3 have such a file.
That would be because the .info files are for Drupal 5, not for 4.7.
"Earl Miles" wrote:
inkfree press wrote:
I have a folder full of 4.7.x downloaded modules, and that's what I searched. I have no idea what's in CVS. I'm talking about what users get if they download a module: only 3 have such a file.
That would be because the .info files are for Drupal 5, not for 4.7.
That has been made clear. These two issues (.info files and updating module "teasers" [*] and/or descriptions) have gotten a bit crossed. I have contributed to that crossing, but let me try to untangle (myself, at least.) Michelle has asked and is waiting for a follow-up regarding the ".info" file system and the full implication of that for 5 and onward. We are, and have been, talking primarily about 4.7.x contrib modules and the cleaning of those (there are 496 when filtered for 4.7.x, as of this date.) I mistakenly connected the idea of ".info" to the current 4.7.x module list, and swung the conversation slightly away from meaningful. The real issue for discussion is the clean-up of the current module descriptions and what method to use to do that so we are forward-looking as well as currently useful (4.7.x will be in use for quite some time.) -- inkfree
On Oct 25, 2006, at 10:26 AM, Michelle Cox wrote:
I recently looked through the entire list of contrib modules and there's some cleanup needed.
* Shorter teasers so the download page isn't so huge * Some modules still need tagging * Modules that are similar could use "See also's"
while we're at it, can we fix another annoying problem: use of <h2> tags in project teasers makes the download pages really confusing. for example, check out: http://drupal.org/project/opensearchclient looks reasonable, since the "OpenSearch Client" part is visually distinct from all the headers. now, go to: http://drupal.org/project/Modules and search for "OpenSearch Client". it's *really* confusing, since all those <h2> headings are the same as the module names. a) seems like we don't need that much info in the project teaser, anyway, and you shouldn't need any <h*> tags to organize your teaser b) i could change theme_project_summary() to do something other than an <h2> for the project titles in these summary pages. however, by convention, it seems like we use an <h2> as the title when displaying a list of nodes. thoughts? -derek (dww)
Derek Wright wrote:
while we're at it, can we fix another annoying problem: use of <h2> tags in project teasers makes the download pages really confusing. for example, check out:
http://drupal.org/project/opensearchclient
looks reasonable, since the "OpenSearch Client" part is visually distinct from all the headers.
now, go to: http://drupal.org/project/Modules and search for "OpenSearch Client".
it's *really* confusing, since all those <h2> headings are the same as the module names.
a) seems like we don't need that much info in the project teaser, anyway, and you shouldn't need any <h*> tags to organize your teaser
b) i could change theme_project_summary() to do something other than an <h2> for the project titles in these summary pages. however, by convention, it seems like we use an <h2> as the title when displaying a list of nodes.
thoughts?
I agree. a) A teaser should not be any more than just that: a teaser. The purpose with a teaser is to puff for the actually content. b) Of course headings should be h3. Why not remove h1 and h2 from the input filter? Regards, Thomas
----- Original Message ----- From: "Derek Wright" <drupal@dwwright.net> To: <development@drupal.org> Sent: Wednesday, October 25, 2006 1:30 PM Subject: Re: [development] Documenting contribs
while we're at it, can we fix another annoying problem: use of <h2> tags in project teasers makes the download pages really confusing. for example, check out:
Yeah, that was part of my "shorter teaser" point in my head... Just didn't make it into my post.
a) seems like we don't need that much info in the project teaser, anyway, and you shouldn't need any <h*> tags to organize your teaser
I agree.
b) i could change theme_project_summary() to do something other than an <h2> for the project titles in these summary pages. however, by convention, it seems like we use an <h2> as the title when displaying a list of nodes.
I like the H2 as the title. If we get rid of them in the teasers, it makes scanning easier. Here's what I'd like to see on the module download page (A wishlist... some of this may not be doable with the current system): * Across the top, alpha links to jump down the page. * Project titles with H2 as they are now * Across the top of each project, off to the right, a list of its tags * Short, no more than a few lines, summary of what the module does. Not just the first few lines of the description, but an actual short summary. No formatting other than bold if really needed. * Under the description, a line for dependencies and a line for see alsos. I need to get my son down for a nap... Will be away from the computer for a while now. Michelle
"Michelle Cox" wrote:
* Shorter teasers so the download page isn't so huge * Some modules still need tagging * Modules that are similar could use "See also's" * Also, there are a lot of modules that aren't documented in the handbook
A thread on the support list went a bit off topic
I also could use some help with this project.
I had not had a chance to reply yet to the request for assistance (esp. regarding the "related modules" stuff) you made on the support list. I did bring up some of the "see also" need that I think could be helpful, and so I should volunteer. ;) [Okay, I do volunteer. I'm not sure exactly what you would like, so let me know.] You mention here the excessive length of some module description entries, which is very valid. Also, some of them contain flat-out advertisements for services, which I think should be a "no no" in any case. They do need to be edited and to be standardized somewhat -- else no real comparison can be made efficiently. So, regarding editing those entries as well as offering some notes on cross-listing [See Also: Module X, Y, Z] or cross-explaining [Module X does similarly, except that...], I'm okay with devoting some time to this task. (I had already decided that the best place for me to contribute is in the Docs area, and I think this is related to that issue, so I believe I can be useful on this chore.) -- inkfree
participants (13)
-
Boris Mann -
Chris Kennedy -
Derek Wright -
Earl Miles -
Gabor Hojtsy -
inkfree press -
James Walker -
Jonathan Lambert -
Khalid B -
Michelle Cox -
Moshe Weitzman -
Thomas Barregren -
Tobias Toedter