From meitarm at gmail.com Sun Jun 1 14:04:44 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Mon, 2 Jun 2008 00:04:44 +1000 Subject: [documentation] Getting involved with documentation efforts: how and where? In-Reply-To: <9f68efb70805300618h3a7aa366va7656db7e2285dd9@mail.gmail.com> References: <9f68efb70805300618h3a7aa366va7656db7e2285dd9@mail.gmail.com> Message-ID: <2237CEB4-EDED-4E83-BAB7-5DBB02D6C35E@gmail.com> Hi Shai, Nat, et. al., Thanks for the warm welcome and the pointers to where to go next. I've followed your links and created a new issue to request to join the docs team: http://drupal.org/node/265234 I'll certainly monitor this listserve, though I suspect I'll be quiet- ish while I find my feet. Since working with Drupal is now my day job and I'm still learning about it, I'll probably spend a fair bit of time on the Drupal.org handbook pages in the coming weeks. Sounds like since I'm in Sydney and much of the Drupal community is in America or Europe, I might not be able to discuss much in real time over IRC or the like. But that's all right, I'll just post here and make what I hope will be helpful edits for a while as I get to know you all. Thanks again for the warm welcome. I'm looking forward to getting to know all of you, as well, Cheers, -- -Meitar Moscovitz Drupal: http://drupal.org/user/265715 Personal: http://maymay.net/ Professional: http://MeitarMoscovitz.com/ On May 30, 2008, at 11:18 PM, Shai Gluskin wrote: > Hi Meitar, > > Great piece on setting up a multisite local development server! > > Meitar, here is the part that may have confused you: Any registered > user of Drupal.org has permissions to create a new handbook page. > That's how you could post the multisite local development piece that > you wrote to the handbook. If you create the page, you can also edit > it. > > In order to edit a handbook page that you did not create, you need > to be on the docs team. I highly recommend that you join the docs > team. Nat Catch gave you the URL and I'll give it to you again: http://drupal.org/project/issues/documentation/ > Create a new issue and put in the title, "Request to Join Docs > Team." It could take from a couple minutes to a couple days to go > through. List your user number and mention that you've written a doc > already. > > It seems like you got hung up a bit on your lack of permission to > assign an issue in the issue queue to anyone other than yourself. > That feature isn't really used by the documentation team, anyway. > Just post away in the Doc issue queue if you have issues to bring up. > > Regarding the issue you raised at: http://drupal.org/node/263767 > (Configuring Apache and PHP for Drupal in a Shared Environment" Best > Practices), which no one responded to: tt was a proposal, actually a > draft, to write another book page. Let me translate the lack of > response: "Meitar, go for it, no objections here." However, I > totally understand that it is hard to read that in the silence. I'm > pleased that you wrote to this list and didn't give up. I'll go > leave a note on that issue now. Your experience teaches a lesson > about how it can be confusing about how to be involved in Drupal. > > I second Nat's suggestion that you join the discussion at: http://drupal.org/node/263767 > , which in some ways is trying to address isues that you bring up. > > How can you help? You already have. More. Keep thinking of handbook > pages that you think need writing and write some of them yourself. > Poke around the handbook and edit other's work (afteryou get doc > team privileges). Monitor this listserve. There are some IRC meeting > being convened by Addi Berry to discuss major upgrades to the > handbook for the upcoming upgrade to Drupal.org; I believe she > always announces those meetings on this list serve. Monitor the > documentation issue queue. > > Thanks for writing and I look forward to working with you and > getting to know you better, > > Shai > content2zero > > > On Fri, May 30, 2008 at 6:41 AM, Nathaniel Catchpole > wrote: > > > > Meitar, > > > > You can edit that page directly if you're a member of the > documentation team. To do that, you just need to follow the process > outlined here: http://drupal.org/node/23367 - the short version is > go to http://drupal.org/project/issues/documentation/ and add a > request. > > > > You also seem to be our exact target for a proposed new block to > make it easier to find information about contributing to > documentation - your input would be very helpful on this issue: http://drupal.org/node/263767 > > > > Nat > > > > > > > > > > On 5/30/08, Mr. Meitar Moscovitz wrote: > >> > >> Hi all, > >> > >> I'm new here, and I'm a developer new to Drupal as well. I've just > >> recently begun working with Drupal full time in a professional > >> context, and in the process have found the existing Drupal docs > to be > >> of invaluable importance in my learning. Naturally, I found some > areas > >> where they could be better, more clear, or are simply lacking. I > >> thought I'd raise my hand to volunteer to help out whatever > >> documentation efforts the Drupal community has and, especially as a > >> new Drupal user and developer, try to flesh out whatever I can so > its > >> more accessible to people without prior Drupal experience or > knowledge. > >> > >> I've already added a few a page of my own to the documentation, not > >> very Drupal-specific but helpful (I think), which you can see at http://drupal.org/user/265715/track > >> > >> A while ago I also put in this documentation issue: http://drupal.org/node/238799 > >> > >> I let it sit for a while since I hadn't had the time to get back > to it? > >> it's always a challenge to balance "getting work done" and "giving > >> back to the community" as I'm sure you al know. In any event, I'd > love > >> to start getting more involved, but don't know precisely how to go > >> about doing that. I figured what better place to ask than here, > on the > >> doc list? > >> > >> Who do I poke about that documentation issue? Where can I go to see > >> other issues that I can help out with (if not the documentation > >> issues, which apparently I need special privileges that I lack to > >> affect). So basically?yeah, where might I be needed, or helpful? > >> > >> By way of delayed introduction, I'm a technical author and a web > >> developer/sysadmin by trade. I'm specifically a front-end > specialist, > >> with a focus on semantic web technologies, and if that's not > enough, > >> I'm dating a writer. :) > >> > >> Cheers, > >> -Meitar Moscovitz > >> > >> Drupal: http://drupal.org/user/265715 > >> Personal: http://maymay.net/ > >> Professional: http://MeitarMoscovitz.com/ > >> > >> > >> -- > >> Pending work: http://drupal.org/project/issues/documentation/ > >> List archives: http://lists.drupal.org/pipermail/documentation/ > > > > > > -- > > Pending work: http://drupal.org/project/issues/documentation/ > > List archives: -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080602/7b2a754b/attachment.htm From shai at content2zero.com Sun Jun 1 14:28:52 2008 From: shai at content2zero.com (Shai Gluskin) Date: Sun, 1 Jun 2008 10:28:52 -0400 Subject: [documentation] Issue Queue vs. Listserve, Roles for Each Message-ID: <9f68efb70806010728k30e1e9d8q668c156491f3bc6a@mail.gmail.com> @meitar has raised an important question, how does one know whether to post something to this docs list serve or to the issue queue? He's also raising the issue of lack of visibility regarding the list serve, which is relevant to the propsed new block for doc pages and being discussed there . This is how I would break down the "When Listserve? When Issue Queue?" question. *Doc listserve*: *discuss* docs strategy, approach, overall problems, announcements for IRC Docs meetings or other Doc meetings like a docs sprint. *Issue queue* *for non-documentation team members: --file as "bug" something that is a mistake in the docs section of the d.o. handbook. (If the person is on the docs team, that person should just fix it; no need to post in the queue.) --Submit request to join the documentation team. *for anyone: --make any formal request to change the way the Drupal project deals with documentation (sometimes these are actually filed in the webmasters queue or the infrastructure queue) --submit support request when desiring help in writing a document. --submit feature request for needed doc that doesn't exist -- but person submitting can't or doesn't want to write it. (If person was able to and wanted to, person could just add it without filing an issue). There is overlap and some duplication in that the responses to a formal proposal made in the queue will certainly contain opinions about the overall approach and strategy of docs, which may previously have come up on the list serve. But when they came up on the list serve, it was part of brainstorming or general discussion, not in the context of a formal proposal, and so it's okay that they are repeated on the issue queue. Another way to think of all this is that the list serve is for vetting and the queue is for action. Do other people agree with this -- have better ways of describing this? Shai -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080601/7e0b2add/attachment.htm From drupal-docs at webchick.net Sun Jun 1 15:14:16 2008 From: drupal-docs at webchick.net (Angela Byron) Date: Sun, 01 Jun 2008 11:14:16 -0400 Subject: [documentation] Issue Queue vs. Listserve, Roles for Each In-Reply-To: <9f68efb70806010728k30e1e9d8q668c156491f3bc6a@mail.gmail.com> References: <9f68efb70806010728k30e1e9d8q668c156491f3bc6a@mail.gmail.com> Message-ID: <4842BCC8.8010404@webchick.net> Shai Gluskin wrote: > @meitar has raised an important question, how does one know whether to > post something to this docs list serve or to the issue queue? He's also > raising the issue of lack of visibility regarding the list serve, which > is relevant to the propsed new block for doc pages and being discussed > there . > > This is how I would break down the "When Listserve? When Issue Queue?" > question. > > *Doc listserve*: /discuss/ docs strategy, approach, overall problems, > announcements for IRC Docs meetings or other Doc meetings like a docs > sprint. ...and for fleshing out an approach enough to make it actionable. See below. > *Issue queue* > *for non-documentation team members: > --file as "bug" something that is a mistake in the docs section of the > d.o. handbook. (If the person is on the docs team, that person should > just fix it; no need to post in the queue.) Actually, docs team members can (and, imo, should) do this just as well. It's best to have a list of all of the docs problems that were too complicated to fix in one quick pass in one place. > --Submit request to join the documentation team. Sadly, yes, but I'd love to figure out a better way for this to happen. NOT in this thread though, please. :D > *for anyone: > --make any formal request to change the way the Drupal project deals > with documentation (sometimes these are actually filed in the webmasters > queue or the infrastructure queue) I would say sure, but *only* after consensus is reached on the mailing lists. If issues have a clear, unified direction on something, they can usually be implemented quickly. When they don't, they just turn into another noisy discussion, but this time each reply is e-mailing several dozen more people than just the folks on the docs list, including folks like Derek Wright, who are *very* busy with many other things, like keeping our download system working and CVS from falling over. This is why I advocated for moving the question of "Why aren't revisions turned on for anon users?" to the issue queue, but NOT the block question, because the docs team (still?) hasn't come to consensus about what it wants to do yet. The place to talk back and forth about the best way to do something is on the docs list, and once consensus is reached on an approach, *then* move it to the issue queue (ideally, with a patch). > --submit support request when desiring help in writing a document. > --submit feature request for needed doc that doesn't exist -- but > person submitting can't or doesn't want to write it. (If person was able > to and wanted to, person could just add it without filing an issue). Yes, and probably also things like "The Multisiter docs really could use some clean-up. Here's how I envision it..." But I file *critical* bug reports against missing API documentation (like hooks), example code that doesn't compile, and stuff like that, but I'm thinking about moving those to the "Drupal" project queue under "documentation" component instead, for increased visibility by the developers who were the ones who didn't document/fix them in the first place, and so the next version of Drupal doesn't go out again with like 25 hooks undocumented. :P~ > There is overlap and some duplication in that the responses to a formal > proposal made in the queue will certainly contain opinions about the > overall approach and strategy of docs, which may previously have come up > on the list serve. But when they came up on the list serve, it was part > of brainstorming or general discussion, not in the context of a formal > proposal, and so it's okay that they are repeated on the issue queue. I disagree w/ this. Get the formal proposal worked out on the discussion list, and when it's *actionable* then move it to the issue queue. > Another way to think of all this is that the list serve is for vetting > and the queue is for action. Exactly! :) -Angie From meitarm at gmail.com Mon Jun 2 07:39:38 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Mon, 2 Jun 2008 17:39:38 +1000 Subject: [documentation] Issue Queue vs. Listserve, Roles for Each In-Reply-To: <4842BCC8.8010404@webchick.net> References: <9f68efb70806010728k30e1e9d8q668c156491f3bc6a@mail.gmail.com> <4842BCC8.8010404@webchick.net> Message-ID: <1AD18A2B-F1BE-48AD-95FB-F91D2ED2CA3F@gmail.com> On Jun 2, 2008, at 1:14 AM, Angela Byron wrote: >> Another way to think of all this is that the list serve is for >> vetting >> and the queue is for action. > > Exactly! :) > > -Angie As a general rule, this makes a lot of sense to me (especially as a newcomer). The question that raises, though, is 'When is something considered "actionable"?' I would imagine that any issue with the docs that can be "fixed" in a quick pass would be "actionable" but doesn't need discussion on this list or on the Docs issues, but something that needs more work (i.e., restructuring, reorganizing, or adding lots of missing content, etc.) would probably be well-served by having some discussion about it. In my (admittedly brief) surfing of docs issues, I haven't been seeing lots of links back to this lists' archives. I imagine it might be even more helpful for docs issues that began as listserve threads have a single link that points back to the archives to provide background for people new to the issue. But then again, maybe I was just looking at the wrong docs issues while browsing. :) Either way, I think aggressive, pervasive interlinking between docs issues and listserve threads would be helpful on all fronts. Angie makes the good point that: >> *Issue queue* >> *for non-documentation team members: >> --file as "bug" something that is a mistake in the docs section of >> the >> d.o. handbook. (If the person is on the docs team, that person should >> just fix it; no need to post in the queue.) > > Actually, docs team members can (and, imo, should) do this just as > well. > It's best to have a list of all of the docs problems that were too > complicated to fix in one quick pass in one place. I'm not that familiar with Drupal's Issues system, but it seems to me that it mirrors functionality from other systems I'm used to like Bugzilla and Trac. In those cases, I'd never make any significant change that doesn't have a ticket or bug report attached to it. Does it make sense to create a doc issue, assign it to myself, then make whatever changes I thought were appropriate to the docs, then close the doc issue, without anyone else ever needing to see it? I'm not sure if there's some overhead to that (other than clicking) that I'm not aware of. Obviously, that's a bit crazy for things like fixing typos or formatting corrections, but it does seem to make sense to me if something biggish needs to happen, and that addresses Angie's point of having "all the docs problems that were too complicated to fix in one quick pass in one place," which can only lead to Good Things, methinks?. Hope that's a clear explanation. I can never tell when I've had this much coffee?. Cheers, -- -Meitar Moscovitz Drupal: http://drupal.org/user/265715 Personal: http://maymay.net Professional: http://MeitarMoscovitz.com From catch56 at googlemail.com Mon Jun 2 09:53:19 2008 From: catch56 at googlemail.com (Nathaniel Catchpole) Date: Mon, 2 Jun 2008 10:53:19 +0100 Subject: [documentation] Issue Queue vs. Listserve, Roles for Each In-Reply-To: <1AD18A2B-F1BE-48AD-95FB-F91D2ED2CA3F@gmail.com> References: <9f68efb70806010728k30e1e9d8q668c156491f3bc6a@mail.gmail.com> <4842BCC8.8010404@webchick.net> <1AD18A2B-F1BE-48AD-95FB-F91D2ED2CA3F@gmail.com> Message-ID: Meitar wrote: __ I'm not that familiar with Drupal's Issues system, but it seems to me that it mirrors functionality from other systems I'm used to like Bugzilla and Trac. In those cases, I'd never make any significant change that doesn't have a ticket or bug report attached to it. Does it make sense to create a doc issue, assign it to myself, then make whatever changes I thought were appropriate to the docs, then close the doc issue, without anyone else ever needing to see it? I'm not sure if there's some overhead to that (other than clicking) that I'm not aware of. __ I think it makes sense to do this for some changes, however there's also the revision log - which allows you to put a message in to explain the edits you've made. If it fits in that box easily, then that's probably enough for most things. Nat -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080602/e7c342da/attachment.htm From meitarm at gmail.com Mon Jun 2 10:56:50 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Mon, 2 Jun 2008 20:56:50 +1000 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting Message-ID: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> Hi all, Surfing the docs issue queue today, I found an issue referring to a formatting fix for the API docs. I did a bit of searching and found this, which talks about how to make API documentation fixes: http://drupal.org/node/144223 I don't have?or want, really?a CVS committer account, mostly because I've never used CVS in my life. (I use Subversion when I have to, but prefer git.) As a result, I'm not entirely sure how to go about progressing this issue: http://drupal.org/node/254522#comment-866484 Seems the issue is fixed for Drupal 7 and CVS HEAD, so I'm betting it's not even a high-priority issue, but that's exactly the kind of issue I'd like to use to familiarize myself with the process. :) I submitted a (`diff -u`) patch against Drupal 6.2, which I uploaded to the comments of the issue report. What happens next? The "Updating API documentation" node seems to want me to use the "Drupal" project, but there isn't an obvious component in that project I can submit the issue against. The original submitter of the issue used the "Documentation" project and selected "Documentation in CVS" as the component, which is exactly what I would have done, not knowing any better. Thanks, -- -Meitar Moscovitz Drupal: http://drupal.org/user/265715 Personal: http://maymay.net Professional: http://MeitarMoscovitz.com From meitarm at gmail.com Mon Jun 2 12:15:53 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Mon, 2 Jun 2008 22:15:53 +1000 Subject: [documentation] Deleting/archiving/moving old book pages? Message-ID: Hi all (again), I'm simply running through a short list of handbook pages that need some copyediting tonight and came across a relatively new one: http://drupal.org/node/265550 This page was created as a subpage of this one: http://drupal.org/node/32109 which also needed a bit of work. I decided it'd be better to just incorporate the two together since they are both about Apache .htaccess files and cache control, and I'm betting the author of the subpage simply created the subpage since they didn't have rights to edit the main page. Now that the two pages are integrated into one, how can I "unpublish" (or delete/archive/move to somewhere else) the old subpage that no longer contains any unique information? I tried looking for a solution myself, but neither the Drupal.org search feature nor Google turned up anything useful. I did find this: http://drupal.org/node/197654 which seems to be the same question as mine asked on December 4th, 2007, but there's no clear answer. I'm surmising from the node itself that I need to create a "bug report" issue for the "Drupal.org webmasters" project, in the "Content moderation" component and ask for an old page to be removed that way. I figured that before I go adding more work for someone else to sort through (i.e., clutter for the webmasters to look at), I'd ask you guys first. :) Am I on the right track with these assumptions? Thanks, -- -Meitar Moscovitz Drupal: http://drupal.org/user/265715 Personal: http://maymay.net Professional: http://MeitarMoscovitz.com From zirvap at gmail.com Mon Jun 2 12:36:43 2008 From: zirvap at gmail.com (Hilde Austlid) Date: Mon, 2 Jun 2008 14:36:43 +0200 Subject: [documentation] Deleting/archiving/moving old book pages? In-Reply-To: References: Message-ID: Hi! 2008/6/2 Mr. Meitar Moscovitz : > Now that the two pages are integrated into one, how can I > "unpublish" (or delete/archive/move to somewhere else) the old subpage > that no longer contains any unique information? I tried looking for a > solution myself, but neither the Drupal.org search feature nor Google > turned up anything useful. I did find this: > > http://drupal.org/node/197654 > > which seems to be the same question as mine asked on December 4th, > 2007, but there's no clear answer. I'm surmising from the node itself > that I need to create a "bug report" issue for the "Drupal.org > webmasters" project, in the "Content moderation" component and ask for > an old page to be removed that way. That's the old way. We recently decided to move them to an "outdated"/"archive" book instead to avoid link rot, see at the bottom of this page: http://drupal.org/documentation-writers-guide (links to discussions at http://drupal.org/node/249778, if you're interested). Regards, Hilde (zirvap) From meitarm at gmail.com Mon Jun 2 13:13:50 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Mon, 2 Jun 2008 23:13:50 +1000 Subject: [documentation] Deleting/archiving/moving old book pages? In-Reply-To: References: Message-ID: On Jun 2, 2008, at 10:36 PM, Hilde Austlid wrote: > Hi! > [?] > We recently decided to move them to an > "outdated"/"archive" book instead to avoid link rot, see at the bottom > of this page: http://drupal.org/documentation-writers-guide (links to > discussions at http://drupal.org/node/249778, if you're interested). > > Regards, Hilde (zirvap) Awesome, that's exactly what I wanted to know. Thanks, Hilde! Cheers, -- -Meitar Moscovitz Drupal: http://drupal.org/user/265715 Personal: http://maymay.net/ Professional: http://MeitarMoscovitz.com/ From fernando at develcuy.com Mon Jun 2 17:11:16 2008 From: fernando at develcuy.com (=?UTF-8?Q?Fernando_P._Garc=C3=ADa?=) Date: Mon, 2 Jun 2008 12:11:16 -0500 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> Message-ID: <5ba75e2f0806021011o698f2f0br10cbafd6fa290d37@mail.gmail.com> Hello Meitar: It concerns the current available resources in drupal.org, and this certainly should be improved but may take a while because is in current plas for rebuilding. So, I suggest to extend API module which stores api data to database, then we should be able to edit descriptions and make suggestions ala l10n_server(ie: look at l10n.drupal-contrib.org). Blessings! On Mon, Jun 2, 2008 at 5:56 AM, Mr. Meitar Moscovitz wrote: > Hi all, > > Surfing the docs issue queue today, I found an issue referring to a > formatting fix for the API docs. I did a bit of searching and found > this, which talks about how to make API documentation fixes: > > http://drupal.org/node/144223 > > I don't have?or want, really?a CVS committer account, mostly because > I've never used CVS in my life. (I use Subversion when I have to, but > prefer git.) As a result, I'm not entirely sure how to go about > progressing this issue: > > http://drupal.org/node/254522#comment-866484 > > Seems the issue is fixed for Drupal 7 and CVS HEAD, so I'm betting > it's not even a high-priority issue, but that's exactly the kind of > issue I'd like to use to familiarize myself with the process. :) > > I submitted a (`diff -u`) patch against Drupal 6.2, which I uploaded > to the comments of the issue report. What happens next? > > The "Updating API documentation" node seems to want me to use the > "Drupal" project, but there isn't an obvious component in that project > I can submit the issue against. The original submitter of the issue > used the "Documentation" project and selected "Documentation in CVS" > as the component, which is exactly what I would have done, not knowing > any better. > > Thanks, > -- > -Meitar Moscovitz > Drupal: http://drupal.org/user/265715 > Personal: http://maymay.net > Professional: http://MeitarMoscovitz.com > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Fernando P. Garc?a, http://www.develcuy.com Developer - Analista de Sistemas +51 1 9 8991 7871, Mz. P Lt. 30 1et Urb. Pachacamac - VES, Lima - Per? -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080602/a54b0450/attachment-0001.htm From darthsteven at gmail.com Mon Jun 2 23:47:57 2008 From: darthsteven at gmail.com (Steven Jones) Date: Tue, 3 Jun 2008 00:47:57 +0100 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> Message-ID: Hello, api.drupal.org has a module (the api module) that parses directories and converts the doxygen comments into lovely html for our viewing pleasure. The complications arise however in what goes in those directories: Drupal core (of the appropriate version) is in the directory, so that things like format_interval, and variable_set have documentation. But hook_nodeapi for example won't be in core, because there is no 'hook' module in core to implement them, the 'hook' is just a placeholder. So instead, there's a special bit of the contrib CVS repo that has extra documentation for these 'phantom' functions. This gets checked out to the directories parsed by a.d.o too. So...if you want to change the documentation on a.d.o then you'll either need to patch core, if that's where the content is coming from, or patch the docs in the contrib repo. If you want to patch core, you should create an issue for the 'Drupal' project, and the 'documentation' component. If you want to patch the docs contrib repo, create an issue for the 'Documentation Project', with the 'documentation in CVS' component. Hope that helps! On Mon, Jun 2, 2008 at 11:56 AM, Mr. Meitar Moscovitz wrote: > Hi all, > > Surfing the docs issue queue today, I found an issue referring to a > formatting fix for the API docs. I did a bit of searching and found > this, which talks about how to make API documentation fixes: > > http://drupal.org/node/144223 > > I don't have?or want, really?a CVS committer account, mostly because > I've never used CVS in my life. (I use Subversion when I have to, but > prefer git.) As a result, I'm not entirely sure how to go about > progressing this issue: > > http://drupal.org/node/254522#comment-866484 > > Seems the issue is fixed for Drupal 7 and CVS HEAD, so I'm betting > it's not even a high-priority issue, but that's exactly the kind of > issue I'd like to use to familiarize myself with the process. :) > > I submitted a (`diff -u`) patch against Drupal 6.2, which I uploaded > to the comments of the issue report. What happens next? > > The "Updating API documentation" node seems to want me to use the > "Drupal" project, but there isn't an obvious component in that project > I can submit the issue against. The original submitter of the issue > used the "Documentation" project and selected "Documentation in CVS" > as the component, which is exactly what I would have done, not knowing > any better. > > Thanks, > -- > -Meitar Moscovitz > Drupal: http://drupal.org/user/265715 > Personal: http://maymay.net > Professional: http://MeitarMoscovitz.com > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Regards Steven Jones From darthsteven at gmail.com Mon Jun 2 23:50:40 2008 From: darthsteven at gmail.com (Steven Jones) Date: Tue, 3 Jun 2008 00:50:40 +0100 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: <5ba75e2f0806021011o698f2f0br10cbafd6fa290d37@mail.gmail.com> References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> <5ba75e2f0806021011o698f2f0br10cbafd6fa290d37@mail.gmail.com> Message-ID: Enabling comments on a.d.o would probably be a huge help, but the documentation of Drupal is scattered enough. We should put more resources into consolidating docs into one place rather than opening new avenues to create different forms of documentation (IMHO). On Mon, Jun 2, 2008 at 6:11 PM, Fernando P. Garc?a wrote: > Hello Meitar: > > It concerns the current available resources in drupal.org, and this > certainly should be improved but may take a while because is in current plas > for rebuilding. > > So, I suggest to extend API module which stores api data to database, then > we should be able to edit descriptions and make suggestions ala > l10n_server(ie: look at l10n.drupal-contrib.org). > > Blessings! > > On Mon, Jun 2, 2008 at 5:56 AM, Mr. Meitar Moscovitz > wrote: >> >> Hi all, >> >> Surfing the docs issue queue today, I found an issue referring to a >> formatting fix for the API docs. I did a bit of searching and found >> this, which talks about how to make API documentation fixes: >> >> http://drupal.org/node/144223 >> >> I don't have?or want, really?a CVS committer account, mostly because >> I've never used CVS in my life. (I use Subversion when I have to, but >> prefer git.) As a result, I'm not entirely sure how to go about >> progressing this issue: >> >> http://drupal.org/node/254522#comment-866484 >> >> Seems the issue is fixed for Drupal 7 and CVS HEAD, so I'm betting >> it's not even a high-priority issue, but that's exactly the kind of >> issue I'd like to use to familiarize myself with the process. :) >> >> I submitted a (`diff -u`) patch against Drupal 6.2, which I uploaded >> to the comments of the issue report. What happens next? >> >> The "Updating API documentation" node seems to want me to use the >> "Drupal" project, but there isn't an obvious component in that project >> I can submit the issue against. The original submitter of the issue >> used the "Documentation" project and selected "Documentation in CVS" >> as the component, which is exactly what I would have done, not knowing >> any better. >> >> Thanks, >> -- >> -Meitar Moscovitz >> Drupal: http://drupal.org/user/265715 >> Personal: http://maymay.net >> Professional: http://MeitarMoscovitz.com >> -- >> Pending work: http://drupal.org/project/issues/documentation/ >> List archives: http://lists.drupal.org/pipermail/documentation/ > > > > -- > Fernando P. Garc?a, http://www.develcuy.com > Developer - Analista de Sistemas > +51 1 9 8991 7871, Mz. P Lt. 30 1et Urb. Pachacamac - VES, Lima - Per? > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Regards Steven Jones From meitarm at gmail.com Tue Jun 3 01:49:47 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Tue, 3 Jun 2008 11:49:47 +1000 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> Message-ID: <22513B22-8006-4ADA-943C-B10F420B4785@gmail.com> Hi Steven, On Jun 3, 2008, at 9:47 AM, Steven Jones wrote: > [?] > If you want to patch core, you should create an issue for the 'Drupal' > project, and the 'documentation' component. > If you want to patch the docs contrib repo, create an issue for the > 'Documentation Project', with the 'documentation in CVS' component. > > Hope that helps! Thanks, that does help. In fact, based on your feedback I was about to go on over to my comment again (at http://drupal.org/node/254522#comment-866484 ) and put the issue in the right queue, but I see it's been done by someone else already. Either way, now I know what the proper places for things like this are. Thanks! -- -Meitar Moscovitz Drupal: http://drupal.org/user/265715 Personal: http://maymay.net Professional: http://MeitarMoscovitz.com From drupal-docs at webchick.net Tue Jun 3 02:03:38 2008 From: drupal-docs at webchick.net (Angela Byron) Date: Mon, 02 Jun 2008 22:03:38 -0400 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: <22513B22-8006-4ADA-943C-B10F420B4785@gmail.com> References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> <22513B22-8006-4ADA-943C-B10F420B4785@gmail.com> Message-ID: <4844A67A.2010002@webchick.net> Mr. Meitar Moscovitz wrote: > Either way, now I know what the proper places for things like this > are. Thanks! Just as a general statement, Meitar, you're asking really great questions that I'm sure all newcomers to the docs team are going to struggle with. How would you feel about making a "Documentation Contribution FAQ" or something like that that, which contains a list of the questions you asked and the answers you've gleaned from the list, in words that a fellow new contributors like yourself could understand? I'd be happy to proof-read it for you, if you'd like. You don't have to, of course, but it just seems like it'd be great to get these things written up somewhere so the *next* time it becomes "Oh, that's covered in the FAQ at . See question #2." :) -Angie From sean at practicalweb.co.uk Tue Jun 3 09:55:42 2008 From: sean at practicalweb.co.uk (Sean Burlington) Date: Tue, 03 Jun 2008 10:55:42 +0100 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> Message-ID: <4845151E.5050505@practicalweb.co.uk> Steven Jones wrote: > But hook_nodeapi for example won't be in core, because there is no > 'hook' module in core to implement them, the 'hook' is just a > placeholder. So instead, there's a special bit of the contrib CVS repo > that has extra documentation for these 'phantom' functions. This gets > checked out to the directories parsed by a.d.o too. > Slight aside (this doesn't address CVS issues) ...hook_nodeapi isn't in core - but node_invoke_nodeapi is - and this is what defines the hook I wonder how hard it would be to alter the api module to recognise hooks in this way - and then to add the references (eg forum_nodeapi) At the moment the only link between these is generated by the comment "implementation of hook_nodeapi" I might have a look at doing this... -- Sean Burlington www.practicalweb.co.uk company number 06427950 From darthsteven at gmail.com Tue Jun 3 11:10:49 2008 From: darthsteven at gmail.com (Steven Jones) Date: Tue, 3 Jun 2008 12:10:49 +0100 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: <4845151E.5050505@practicalweb.co.uk> References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> <4845151E.5050505@practicalweb.co.uk> Message-ID: I wouldn't say that node_invoke_nodeapi 'defined' the nodeapi hook. It invokes it, because module_invoke_all can't handle references. But I think that for people looking for how to use the nodeapi hook are much more likely to tap 'hook_nodeapi' into a.d.o. You don't need knowledge of how the hook is invoked to implement it, you just need to know what parameters you get etc. On Tue, Jun 3, 2008 at 10:55 AM, Sean Burlington wrote: > Steven Jones wrote: >> But hook_nodeapi for example won't be in core, because there is no >> 'hook' module in core to implement them, the 'hook' is just a >> placeholder. So instead, there's a special bit of the contrib CVS repo >> that has extra documentation for these 'phantom' functions. This gets >> checked out to the directories parsed by a.d.o too. >> > > Slight aside (this doesn't address CVS issues) > > ...hook_nodeapi isn't in core - but node_invoke_nodeapi is > > - and this is what defines the hook > > I wonder how hard it would be to alter the api module to recognise hooks > in this way - and then to add the references (eg forum_nodeapi) > > At the moment the only link between these is generated by the comment > "implementation of hook_nodeapi" > > I might have a look at doing this... > > -- > > Sean Burlington > > www.practicalweb.co.uk > company number 06427950 > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Regards Steven Jones From meitarm at gmail.com Tue Jun 3 11:11:09 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Tue, 3 Jun 2008 21:11:09 +1000 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: <4844A67A.2010002@webchick.net> References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> <22513B22-8006-4ADA-943C-B10F420B4785@gmail.com> <4844A67A.2010002@webchick.net> Message-ID: <66E4CAB1-62F8-419F-872E-64029400D102@gmail.com> On Jun 3, 2008, at 12:03 PM, Angela Byron wrote: > Mr. Meitar Moscovitz wrote: > >> Either way, now I know what the proper places for things like this >> are. Thanks! > > Just as a general statement, Meitar, you're asking really great > questions that I'm sure all newcomers to the docs team are going to > struggle with. How would you feel about making a "Documentation > Contribution FAQ" or something like that that, which contains a list > of the questions you asked and the answers you've gleaned from the > list, in words that a fellow new contributors like yourself could > understand? I'd be happy to proof-read it for you, if you'd like. That makes sense to me. I'm sure most of the answers to such questions already exist in many places, but in all the places that I've found what turned out to be correct answers, they were pretty brief and hard to interpret. For instance, here, in "Updating API documentation" http://drupal.org/node/144223 there's a short section headlined "Code" that has two sentences in it: > All documentation for core functions, constants, and files are > automatically generated from the core modules in Drupal. [?] To > update these, you must submit a core patch to edit the Doxygen > comments of the code in question. The text "submit a core patch" is a link to the http://drupal.org/node/add/project-issue/drupal page, which is far from explanatory for someone like me (until yesterday, when Steven clued me into the details). Better, IMHO, would be a paragraph or two (tops) with appropriate links embedded in natural text to places such as "Doxygen formatting conventions" (http://drupal.org/node/1354 ) and so forth, so the reader doesn't have to reach for the search box in a ridiculous number of browser tabs. :) So I guess my question is, do you think there's really a need for a FAQ, or should I just spend a little while going through some of the child pages to "Contributing to documentation" and fleshing them out further? Of course, I could always do *that*, and then *also* compose a list of all the questions I'm asking, run them by you or a mailing list archive search to see how frequent they are, and then post brief one- liners with appropriate links in a new "Contributing to documentation FAQ", as well?. > You don't have to, of course, but it just seems like it'd be great > to get these things written up somewhere so the *next* time it > becomes "Oh, that's covered in the FAQ at . See question #2." :) > > -Angie I didn't have to ask to join the Drupal docs team either, now did I? ;) Cheers, -- -Meitar Moscovitz Drupal: http://drupal.org/user/265715 Personal: http://maymay.net Professional: http://MeitarMoscovitz.com From sean at practicalweb.co.uk Tue Jun 3 11:22:08 2008 From: sean at practicalweb.co.uk (Sean Burlington) Date: Tue, 03 Jun 2008 12:22:08 +0100 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> <4845151E.5050505@practicalweb.co.uk> Message-ID: <48452960.70707@practicalweb.co.uk> Steven Jones wrote: > I wouldn't say that node_invoke_nodeapi 'defined' the nodeapi hook. It > invokes it, because module_invoke_all can't handle references. My understanding is that creating a function called mymodule_invoke_dosomething() will cause Drupal (via module_invoke_all() ?) to call functions in other modules called othermodule_dosomething() Is there another step in hook creation that I'm missing? > But I think that for people looking for how to use the nodeapi hook > are much more likely to tap 'hook_nodeapi' into a.d.o. You don't need > knowledge of how the hook is invoked to implement it, you just need to > know what parameters you get etc. > I agree - I'm just wondering if we (maybe me) could automate the creation of the hook_nodapi page. - and at the same time look for functions that are implementations of the hook so that the hook_nodapi references has links to all the places the hook is used. This would be especially useful for my use of the API module on sites I work on - where I would be able to look (for example) for all the places the site uses hook_form_alter(). -- Sean Burlington www.practicalweb.co.uk company number 06427950 From darthsteven at gmail.com Tue Jun 3 11:38:24 2008 From: darthsteven at gmail.com (Steven Jones) Date: Tue, 3 Jun 2008 12:38:24 +0100 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: <48452960.70707@practicalweb.co.uk> References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> <4845151E.5050505@practicalweb.co.uk> <48452960.70707@practicalweb.co.uk> Message-ID: Hi, > My understanding is that creating a function called > > mymodule_invoke_dosomething() > > will cause Drupal (via module_invoke_all() ?) to call functions in other > modules called othermodule_dosomething() > > Is there another step in hook creation that I'm missing? You need to call module_invoke_all giving the name of the hook that you want to invoke as the first parameter, and the rest of the parameters of the hook. It will return a merged array of all the results from those modules that implement that hook. See: http://api.drupal.org/api/function/module_invoke_all/6 You *may* want to put the call to module_invoke_all in a wrapper function in *your* module, which mymodule_invoke_hookname would be a good place, but there's no hard and fast rule AFAIK. > I agree - I'm just wondering if we (maybe me) could automate the > creation of the hook_nodapi page. It is! a.d.o checks out a file from CVS, http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/hooks/, and that's where the http://api.drupal.org/api/function/hook_nodeapi/6 page comes from. > - and at the same time look for functions that are implementations of > the hook so that the hook_nodapi references has links to all the places > the hook is used. They'll need to be named modulename_nodeapi so finding implementations is fairly trivial, just use the search box on a.d.o and type in: "_nodeapi" Also, we're getting a little off-topic here :-D On Tue, Jun 3, 2008 at 12:22 PM, Sean Burlington wrote: > Steven Jones wrote: >> I wouldn't say that node_invoke_nodeapi 'defined' the nodeapi hook. It >> invokes it, because module_invoke_all can't handle references. > > My understanding is that creating a function called > > mymodule_invoke_dosomething() > > will cause Drupal (via module_invoke_all() ?) to call functions in other > modules called othermodule_dosomething() > > Is there another step in hook creation that I'm missing? > > >> But I think that for people looking for how to use the nodeapi hook >> are much more likely to tap 'hook_nodeapi' into a.d.o. You don't need >> knowledge of how the hook is invoked to implement it, you just need to >> know what parameters you get etc. >> > > I agree - I'm just wondering if we (maybe me) could automate the > creation of the hook_nodapi page. > > - and at the same time look for functions that are implementations of > the hook so that the hook_nodapi references has links to all the places > the hook is used. > > This would be especially useful for my use of the API module on sites I > work on - where I would be able to look (for example) for all the places > the site uses hook_form_alter(). > > > > -- > > Sean Burlington > > www.practicalweb.co.uk > company number 06427950 > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Regards Steven Jones -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080603/e6119072/attachment.htm From darthsteven at gmail.com Tue Jun 3 11:43:29 2008 From: darthsteven at gmail.com (Steven Jones) Date: Tue, 3 Jun 2008 12:43:29 +0100 Subject: [documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting In-Reply-To: <66E4CAB1-62F8-419F-872E-64029400D102@gmail.com> References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> <22513B22-8006-4ADA-943C-B10F420B4785@gmail.com> <4844A67A.2010002@webchick.net> <66E4CAB1-62F8-419F-872E-64029400D102@gmail.com> Message-ID: Hi, I'd imagine writing a FAQ by yourself would be a huge undertaking, instead, why don't you create an issue in the queue (documentation project) and just list any questions that you can think of, others can do the same and then gradually we can move them over into handbook pages. If we make each question its own page then the handbook theming will give us a nice list of all of them on the parent page. If there were a list of 'Unanswered FAQs' then I'd happily spend ten minutes every now and then writing an answer to one and adding it. If other's did the same we'd get a high quality FAQ list in no time. On Tue, Jun 3, 2008 at 12:11 PM, Mr. Meitar Moscovitz wrote: > On Jun 3, 2008, at 12:03 PM, Angela Byron wrote: > > > Mr. Meitar Moscovitz wrote: > > > >> Either way, now I know what the proper places for things like this > >> are. Thanks! > > > > Just as a general statement, Meitar, you're asking really great > > questions that I'm sure all newcomers to the docs team are going to > > struggle with. How would you feel about making a "Documentation > > Contribution FAQ" or something like that that, which contains a list > > of the questions you asked and the answers you've gleaned from the > > list, in words that a fellow new contributors like yourself could > > understand? I'd be happy to proof-read it for you, if you'd like. > > That makes sense to me. I'm sure most of the answers to such questions > already exist in many places, but in all the places that I've found > what turned out to be correct answers, they were pretty brief and hard > to interpret. For instance, here, in "Updating API documentation" > http://drupal.org/node/144223 > there's a short section headlined "Code" that has two sentences in it: > > > All documentation for core functions, constants, and files are > > automatically generated from the core modules in Drupal. [?] To > > update these, you must submit a core patch to edit the Doxygen > > comments of the code in question. > > > The text "submit a core patch" is a link to the > http://drupal.org/node/add/project-issue/drupal > page, which is far from explanatory for someone like me (until > yesterday, when Steven clued me into the details). Better, IMHO, would > be a paragraph or two (tops) with appropriate links embedded in > natural text to places such as "Doxygen formatting conventions" ( > http://drupal.org/node/1354 > ) and so forth, so the reader doesn't have to reach for the search box > in a ridiculous number of browser tabs. :) > > So I guess my question is, do you think there's really a need for a > FAQ, or should I just spend a little while going through some of the > child pages to "Contributing to documentation" and fleshing them out > further? > > Of course, I could always do *that*, and then *also* compose a list of > all the questions I'm asking, run them by you or a mailing list > archive search to see how frequent they are, and then post brief one- > liners with appropriate links in a new "Contributing to documentation > FAQ", as well?. > > > You don't have to, of course, but it just seems like it'd be great > > to get these things written up somewhere so the *next* time it > > becomes "Oh, that's covered in the FAQ at . See question #2." :) > > > > -Angie > > > I didn't have to ask to join the Drupal docs team either, now did I? ;) > > Cheers, > -- > -Meitar Moscovitz > Drupal: http://drupal.org/user/265715 > Personal: http://maymay.net > Professional: http://MeitarMoscovitz.com > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Regards Steven Jones -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080603/eaaa785c/attachment.htm From meitarm at gmail.com Wed Jun 4 05:31:22 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Wed, 4 Jun 2008 15:31:22 +1000 Subject: [documentation] Please consider contributing to "Contributing to documenation FAQ" (was Re: Need CVS + Drupal Issues guidance: How to help fix API documentation formatting) In-Reply-To: References: <00EE3D47-C490-46BC-9A95-8E4BC2B88BC3@gmail.com> <22513B22-8006-4ADA-943C-B10F420B4785@gmail.com> <4844A67A.2010002@webchick.net> <66E4CAB1-62F8-419F-872E-64029400D102@gmail.com> Message-ID: <2DA3BD8C-2883-412D-A2CB-4465B20F951F@gmail.com> On Jun 3, 2008, at 9:43 PM, Steven Jones wrote: > Hi, > > I'd imagine writing a FAQ by yourself would be a huge undertaking, > instead, why don't you create an issue in the queue (documentation > project) and just list any questions that you can think of, others > can do the same and then gradually we can move them over into > handbook pages. If we make each question its own page then the > handbook theming will give us a nice list of all of them on the > parent page. > > If there were a list of 'Unanswered FAQs' then I'd happily spend > ten minutes every now and then writing an answer to one and adding > it. If other's did the same we'd get a high quality FAQ list in no > time. Done. See: http://drupal.org/node/266439 I've assigned this ticket to myself and will monitor it for the time being. I'll also add some questions when I get the chance to do so, and then start composing such a FAQ (probably on a new Book page so you can all edit it as well). Will update the issue when the book page is created and has some interesting content to review. Thanks, -- -Meitar Moscovitz Personal: http://maymay.net Professional: http://MeitarMoscovitz.com From catch56 at googlemail.com Wed Jun 4 09:06:07 2008 From: catch56 at googlemail.com (Nathaniel Catchpole) Date: Wed, 4 Jun 2008 10:06:07 +0100 Subject: [documentation] [development] lightbox module comparison In-Reply-To: <127343.21565.qm@web65614.mail.ac4.yahoo.com> References: <127343.21565.qm@web65614.mail.ac4.yahoo.com> Message-ID: I've moved this up to the top level of "beyond the basics" (alongside snippets, modules, themes, howtos etc.). And it's even got a WYSIWYG comparison in it (although a few months old now). I'd quite like to see a comparison of the various 'related/similar content' modules - there must be at least 10-15 by now. Image modules would be a massive help for newbies. Must be lots of others. Nat On 6/4/08, Karen Stevenson wrote: > > I think a 'module comparisons' section is important enough to deserve a > top-level place in the handbook, with a link from the downloads page to make > it easy for someone looking for modules to find. I actually think writeups > like this are far more useful that the contrib module rating system that is > often discussed. What does a 5 star rating tell you? It tells you the module > solved a specific problem for the person who rated it, it doesn't tell you > if it will solve *your* problem or be useful in *your* situation. But this > kind of writeup makes it easy to see which module is the best fit for your > particular situation, which is really really useful. > > This should not be buried down in the module documentation -- someone > looking at one of the other modules would never see it. It should be very > prominent (and that hopefully would also encourage other people to add more > of these kinds of comparisons). > > For instance a good comparison of the different wysiwyg editors would be > pretty useful :) > > Karen > > -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080604/6046c63e/attachment-0001.htm From stella at stellapower.net Wed Jun 4 19:20:26 2008 From: stella at stellapower.net (Stella Power) Date: Wed, 4 Jun 2008 20:20:26 +0100 Subject: [documentation] [development] lightbox module comparison In-Reply-To: <127343.21565.qm@web65614.mail.ac4.yahoo.com> References: <127343.21565.qm@web65614.mail.ac4.yahoo.com> Message-ID: I think we may also need a comparison on the different "access" modules available. For example, there's "node access", "taxonomy access control", "taxonomy access control lite", "simple access", "path access", "url access", ... While I'm sure they all do different things, it would be useful to an overview page of the features provided by each. I also wouldn't mind a comparison on the ecommerce modules available in Drupal, though perhaps that would be too big a task for one person! I'm sure I saw a comparison of e-commerce and ubercart somewhere on the web, can't find it right now, but it might be another useful link to add to this section of the handbook. It might be useful to see comparisons that other users want too. Should users create documentation tasks? Or should they just scratch their own itch? I'm already a member of the docs team and certainly wouldn't mind helping with this. Cheers, Stella On Wed, Jun 4, 2008 at 2:25 AM, Karen Stevenson wrote: > I think a 'module comparisons' section is important enough to deserve a > top-level place in the handbook, with a link from the downloads page to make > it easy for someone looking for modules to find. I actually think writeups > like this are far more useful that the contrib module rating system that is > often discussed. What does a 5 star rating tell you? It tells you the module > solved a specific problem for the person who rated it, it doesn't tell you > if it will solve *your* problem or be useful in *your* situation. But this > kind of writeup makes it easy to see which module is the best fit for your > particular situation, which is really really useful. > > This should not be buried down in the module documentation -- someone > looking at one of the other modules would never see it. It should be very > prominent (and that hopefully would also encourage other people to add more > of these kinds of comparisons). > > For instance a good comparison of the different wysiwyg editors would be > pretty useful :) > > Karen > > ----- Original Message ---- > From: FGM > To: development at drupal.org > Sent: Tuesday, June 3, 2008 10:27:32 AM > Subject: Re: [development] lightbox module comparison > > I've done one on the two glossary modules I'm aware of (glossary.module and > g2.module), it's on the g2 project page. Maybe there are more, though ? > > This being said, you might have something: module duplication and module > voting being recurrent themes, it might make sense to formalize a rule > like: > "if you're doing a module that resembles other modules, create a comparison > page, that will go in the section of the handbook", in > the dev manual. > > What do you think of it ? > > FGM > -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080604/8f77dc65/attachment.htm From stella at stellapower.net Wed Jun 4 22:48:25 2008 From: stella at stellapower.net (Stella Power) Date: Wed, 4 Jun 2008 23:48:25 +0100 Subject: [documentation] [development] lightbox module comparison In-Reply-To: References: Message-ID: Well I plan on keeping the lightbox comparison page up to date, hopefully with some updates from the individual module maintainers. It's also why I have a "Last Updated" bit at the top of the comparison, so people reading it can see exactly how recent it is. I also have a date beside each module in the first overview table to show when the info on that particular module was last updated. Cheers, Stella On Wed, Jun 4, 2008 at 11:42 PM, Larry Garfield wrote: > > I agree that these comparison pages are very valuable; no question. > However, one problem with them is that they are also time-sensitive. I > don't expect any of the modules mentioned to stand still. That means much > of the data is going to become outdated; some in a month, some in 6 months. > Are we also committing to keeping these pages up to date? Out of > date/wrong documentation can be just as bad if not worse than no > documentation at all. > > --Larry Garfield the killjoy > > On Wed, 4 Jun 2008 20:21:54 +0100, "Stella Power" > wrote: > > I added one to the lightbox2 module page too. > > > > > > On Wed, Jun 4, 2008 at 10:05 AM, Richard Burford < > > rich at freestylesystems.co.uk> wrote: > > > >> Agreed. A link from each module page to the comparison would be good a > > good > >> addition. I'll add one for Shadowbox now. > >> > >> psynaptic > >> http://freestylesystems.co.uk > >> http://api.freestylesystems.co.uk > >> > >> > >> On 4 Jun 2008, at 02:25, Karen Stevenson wrote: > >> > >> I think a 'module comparisons' section is important enough to deserve a > >>> top-level place in the handbook, with a link from the downloads page to > > make > >>> it easy for someone looking for modules to find. I actually think > > writeups > >>> like this are far more useful that the contrib module rating system > > that is > >>> often discussed. What does a 5 star rating tell you? It tells you the > > module > >>> solved a specific problem for the person who rated it, it doesn't tell > > you > >>> if it will solve *your* problem or be useful in *your* situation. But > > this > >>> kind of writeup makes it easy to see which module is the best fit for > > your > >>> particular situation, which is really really useful. > >>> > >>> This should not be buried down in the module documentation -- someone > >>> looking at one of the other modules would never see it. It should be > > very > >>> prominent (and that hopefully would also encourage other people to add > > more > >>> of these kinds of comparisons). > >>> > >>> For instance a good comparison of the different wysiwyg editors would > > be > >>> pretty useful :) > >>> > >>> Karen > >>> > >>> ----- Original Message ---- > >>> From: FGM > >>> To: development at drupal.org > >>> Sent: Tuesday, June 3, 2008 10:27:32 AM > >>> Subject: Re: [development] lightbox module comparison > >>> > >>> I've done one on the two glossary modules I'm aware of (glossary.module > >>> and > >>> g2.module), it's on the g2 project page. Maybe there are more, though ? > >>> > >>> This being said, you might have something: module duplication and > > module > >>> voting being recurrent themes, it might make sense to formalize a rule > >>> like: > >>> "if you're doing a module that resembles other modules, create a > >>> comparison > >>> page, that will go in the section of the handbook", > > in > >>> the dev manual. > >>> > >>> What do you think of it ? > >>> > >>> FGM > >>> > >> > >> > > > > > > -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080604/13bd7a9f/attachment.htm From catch56 at googlemail.com Wed Jun 4 23:47:58 2008 From: catch56 at googlemail.com (Nathaniel Catchpole) Date: Thu, 5 Jun 2008 00:47:58 +0100 Subject: [documentation] 'Last updated' information on handbook pages? Message-ID: The idea came up in this thread on the development list: http://lists.drupal.org/pipermail/development/2008-June/030088.html (which is more about documentation than development). I think it's a good one - display last updated information on all handbook pages. It'd be one line to add in Bluebeach, and it immediately helps with evaluating whether a page is up to date or not. Is there any reason not to do this? Nat -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/f78f5f65/attachment.htm From darthsteven at gmail.com Thu Jun 5 08:09:36 2008 From: darthsteven at gmail.com (Steven Jones) Date: Thu, 5 Jun 2008 09:09:36 +0100 Subject: [documentation] 'Last updated' information on handbook pages? In-Reply-To: References: Message-ID: Hi, Showing the last updated time doesn't show you that the page is up to date, it only shows you how out of date it could be. If I fix a typo on a page, then having that date displayed will make it look like that was the last date that the content was checked for accuracy. So while on the surface a good idea, I'm not sure how misleading the information could be. On Thu, Jun 5, 2008 at 12:47 AM, Nathaniel Catchpole wrote: > The idea came up in this thread on the development list: > http://lists.drupal.org/pipermail/development/2008-June/030088.html (which > is more about documentation than development). > > I think it's a good one - display last updated information on all handbook > pages. It'd be one line to add in Bluebeach, and it immediately helps with > evaluating whether a page is up to date or not. > > Is there any reason not to do this? > > Nat > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Regards Steven Jones -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/2d06d18a/attachment.htm From meitarm at gmail.com Thu Jun 5 08:35:03 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Thu, 5 Jun 2008 18:35:03 +1000 Subject: [documentation] 'Last updated' information on handbook pages? In-Reply-To: References: Message-ID: <68548D2B-A18F-4FDD-8FD5-D4367F110943@gmail.com> On Jun 5, 2008, at 6:09 PM, Steven Jones wrote: > Hi, > > Showing the last updated time doesn't show you that the page is up > to date, it only shows you how out of date it could be. If I fix a > typo on a page, then having that date displayed will make it look > like that was the last date that the content was checked for accuracy. > > So while on the surface a good idea, I'm not sure how misleading the > information could be. Hi, If this were me?and I do realize I'm probably not a very good example of a typical user persona?and I read a page that was somewhat out of date but saw a recent last-modified time stamp on the page, I would check the revisions tab to see what the last couple of revision log messages are. Hopefully there will actually be some revision log message there that just says "Fixed typo", so I'd be able to quickly see what the latest major update/change was. If not, I'd probably run a diff. Since, (if I understand correctly) all visitors logged in with a d.o user account (doc team members or otherwise) have access to the revisions tab, I don't think it's too misleading in these cases to add a last-modified time stamp. The information is in the worst case *somewhat* misleading but in the best case *very* helpful, so I think adding this time stamp seems like an overall net win for visitors. Plus, if users get upset about seeing mismatched time stamps to out of date pages, perhaps they will be encouraged to add more issues that notify us of this fact! My two cents?. Cheers, -- -Meitar Moscovitz Drupal: http://drupal.org/user/265715 Personal: http://maymay.net Professional: http://MeitarMoscovitz.com > On Thu, Jun 5, 2008 at 12:47 AM, Nathaniel Catchpole > wrote: > The idea came up in this thread on the development list: http://lists.drupal.org/pipermail/development/2008-June/030088.html > (which is more about documentation than development). > > I think it's a good one - display last updated information on all > handbook pages. It'd be one line to add in Bluebeach, and it > immediately helps with evaluating whether a page is up to date or not. > > Is there any reason not to do this? > > Nat > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > > > > -- > Regards > Steven Jones -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/e490c6b1/attachment-0001.htm From catch56 at googlemail.com Thu Jun 5 09:08:06 2008 From: catch56 at googlemail.com (Nathaniel Catchpole) Date: Thu, 5 Jun 2008 10:08:06 +0100 Subject: [documentation] 'Last updated' information on handbook pages? In-Reply-To: <68548D2B-A18F-4FDD-8FD5-D4367F110943@gmail.com> References: <68548D2B-A18F-4FDD-8FD5-D4367F110943@gmail.com> Message-ID: I agree with Meitar. I don't think having recently updated timestamps on out of date information is going to lull people into a false sense of security - at least not compared to now, where they appear pretty much timeless except for the version taxonomy. This came up specifically in the case of module comparisons - if I see that a page comparing modules hasn't been updated for 6 months, then hopefully it'll indicate that things might have changed since then and encourage me to update it. At the moment, I have no idea either way unless I check the revisions tab (and I rarely do this unless I'm about to archive a page or make a big edit, hardly ever if I'm actually reading documentation). Also, if I see a page that hasn't been updated since 2006 or something, then it's an extra bit of encouragement to jump in and fix it. Nat -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/bf7f776e/attachment.htm From catch56 at googlemail.com Thu Jun 5 10:01:32 2008 From: catch56 at googlemail.com (Nathaniel Catchpole) Date: Thu, 5 Jun 2008 11:01:32 +0100 Subject: [documentation] Add disclaimer to all handbook pages Message-ID: Whilst thinking about the contributors block and last updated info, it occurred to me we don't have a disclaimer displayed for all handbook pages. I think it'd make sense to have something displayed on all pages to make it clear that it's community contributed documentation etc. - might be worth putting in the contributors block. "All documentation is contributed by volunteers and may not have been checked for accuracy" something like that. For example, code snippets probably need this more than most. http://drupal.org/handbook/customization/snippets - has a disclaimer http://drupal.org/node/45471 - (theme snippets parent) has a disclaimer http://drupal.org/node/35728 - an actual code snippet, doesn't have a disclaimer. Unless I find the snippet via the handbook hierarchy (and IMO more people will find it from incoming links, irc, google and drupal.orgsearch than clicking through), I won't see the disclaimer. If the block happens, then it's just an extra sentence to add, but it'd need to be carefully worded - since equally we don't want to give the idea that there's official, non-volunteer documentation hiding somewhere. Nat -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/6afeb01f/attachment.htm From nesrekaradag at hotmail.co.uk Thu Jun 5 10:04:32 2008 From: nesrekaradag at hotmail.co.uk (Nesre Karadag) Date: Thu, 5 Jun 2008 11:04:32 +0100 Subject: [documentation] [development] lightbox module comparison In-Reply-To: References: <127343.21565.qm@web65614.mail.ac4.yahoo.com> Message-ID: I don't want to recieve these e-mails anymore... Date: Wed, 4 Jun 2008 10:06:07 +0100From: catch56 at googlemail.comTo: development at drupal.org; documentation at drupal.orgSubject: Re: [documentation] [development] lightbox module comparisonI've moved this up to the top level of "beyond the basics" (alongside snippets, modules, themes, howtos etc.). And it's even got a WYSIWYG comparison in it (although a few months old now). I'd quite like to see a comparison of the various 'related/similar content' modules - there must be at least 10-15 by now. Image modules would be a massive help for newbies. Must be lots of others. NatOn 6/4/08, Karen Stevenson wrote: I think a 'module comparisons' section is important enough to deserve a top-level place in the handbook, with a link from the downloads page to make it easy for someone looking for modules to find. I actually think writeups like this are far more useful that the contrib module rating system that is often discussed. What does a 5 star rating tell you? It tells you the module solved a specific problem for the person who rated it, it doesn't tell you if it will solve *your* problem or be useful in *your* situation. But this kind of writeup makes it easy to see which module is the best fit for your particular situation, which is really really useful.This should not be buried down in the module documentation -- someone looking at one of the other modules would never see it. It should be very prominent (and that hopefully would also encourage other people to add more of these kinds of comparisons).For instance a good comparison of the different wysiwyg editors would be pretty useful :)Karen _________________________________________________________________ http://clk.atdmt.com/UKM/go/msnnkmgl0010000007ukm/direct/01/ -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/e64bbce3/attachment.htm From meitarm at gmail.com Thu Jun 5 12:16:21 2008 From: meitarm at gmail.com (Mr. Meitar Moscovitz) Date: Thu, 5 Jun 2008 22:16:21 +1000 Subject: [documentation] Add disclaimer to all handbook pages In-Reply-To: References: Message-ID: <5B2E5B8E-E489-497A-A95A-913E78F6EF4F@gmail.com> On Jun 5, 2008, at 8:01 PM, Nathaniel Catchpole wrote: > Whilst thinking about the contributors block and last updated info, > it occurred to me we don't have a disclaimer displayed for all > handbook pages. I think it'd make sense to have something displayed > on all pages to make it clear that it's community contributed > documentation etc. - might be worth putting in the contributors > block. "All documentation is contributed by volunteers and may not > have been checked for accuracy" something like that. I'm kind of just wondering aloud here, but isn't it pretty obvious that Drupal is entirely a community-driven, volunteer-run project, and that *all* of its code/documentation has come from volunteers and may not have been checked for accuracy? I can see that there's certainly a fine line to walk here, but since any d.o user account can add a new handbook page, I would imagine that it's pretty self-evident where the documentation comes from. So as not to be nothing but a dissenter, what about this idea: rather than blanket the entire handbook with a big disclaimer, why not develop a set of standard snippets that we as doc team members can add to pages we feel are dangerous, risky, or need any other kind of red- flag placed on them. I'm thinking something along the lines of Wikipedia's "The community feels that this article might need revision?" sort of things. See any of the massive list of template messages at http://en.wikipedia.org/wiki/Wikipedia:Template_messages for examples. Currently, it seems to me that the docs team does do this, but we do this by submitting issues against certain nodes, which are not visible from the handbook pages themselves and thus no user browsing the handbook pages would see them. Using something akin to Wikipedia's template messages system (which is purely enforced by convention, not by the software?which is sensible if you ask me), would remedy that problem. Of course, I have no idea what the technical implementation of that would look like. Just brainstorming here. Cheers, -- -Meitar Moscovitz Personal: http://maymay.net Professional: http://MeitarMoscovitz.com > For example, code snippets probably need this more than most. > > http://drupal.org/handbook/customization/snippets - has a disclaimer > http://drupal.org/node/45471 - (theme snippets parent) has a > disclaimer > http://drupal.org/node/35728 - an actual code snippet, doesn't have > a disclaimer. Unless I find the snippet via the handbook hierarchy > (and IMO more people will find it from incoming links, irc, google > and drupal.org search than clicking through), I won't see the > disclaimer. > > If the block happens, then it's just an extra sentence to add, but > it'd need to be carefully worded - since equally we don't want to > give the idea that there's official, non-volunteer documentation > hiding somewhere. > > Nat > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/073f930c/attachment.htm From shai at content2zero.com Thu Jun 5 13:28:26 2008 From: shai at content2zero.com (Shai Gluskin) Date: Thu, 5 Jun 2008 09:28:26 -0400 Subject: [documentation] 'Last updated' information on handbook pages? In-Reply-To: References: <68548D2B-A18F-4FDD-8FD5-D4367F110943@gmail.com> Message-ID: <9f68efb70806050628u3d906f77wac22b59ca54f162c@mail.gmail.com> I agree with Nat and Meitar, That time stamp is a data point. From reading the NYTimes to Wikipedia to Drupal.org a reader is obligated to assess the value/limitations of any particular piece of information. I think it is paternalistic to keep information out of folks hands because of a possibility that some folks might misinterpret the meaning of it. Reasons not to show information: * causes usability problems by mucking up presentation or page clarity. * takes up valuable system resources like running an "expensive" query. As long as it passes these tests, I'd be in favor. Shai On Thu, Jun 5, 2008 at 5:08 AM, Nathaniel Catchpole wrote: > I agree with Meitar. I don't think having recently updated timestamps on > out of date information is going to lull people into a false sense of > security - at least not compared to now, where they appear pretty much > timeless except for the version taxonomy. > > This came up specifically in the case of module comparisons - if I see that > a page comparing modules hasn't been updated for 6 months, then hopefully > it'll indicate that things might have changed since then and encourage me to > update it. At the moment, I have no idea either way unless I check the > revisions tab (and I rarely do this unless I'm about to archive a page or > make a big edit, hardly ever if I'm actually reading documentation). > > Also, if I see a page that hasn't been updated since 2006 or something, > then it's an extra bit of encouragement to jump in and fix it. > > Nat > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/a6c3bec0/attachment-0001.htm From fernando at develcuy.com Thu Jun 5 14:45:04 2008 From: fernando at develcuy.com (=?UTF-8?Q?Fernando_P._Garc=C3=ADa?=) Date: Thu, 5 Jun 2008 09:45:04 -0500 Subject: [documentation] Add disclaimer to all handbook pages In-Reply-To: <5B2E5B8E-E489-497A-A95A-913E78F6EF4F@gmail.com> References: <5B2E5B8E-E489-497A-A95A-913E78F6EF4F@gmail.com> Message-ID: <5ba75e2f0806050745t75ab2c1sa4694d0baaba71fd@mail.gmail.com> I agree with Nathaniel, Disclaimer makes sense, but may this concern Drupal Association? So I just request this but can't provide any idea to solve this polemic issue. Blessings! On Thu, Jun 5, 2008 at 7:16 AM, Mr. Meitar Moscovitz wrote: > On Jun 5, 2008, at 8:01 PM, Nathaniel Catchpole wrote: > > Whilst thinking about the contributors block and last updated info, it > occurred to me we don't have a disclaimer displayed for all handbook pages. > I think it'd make sense to have something displayed on all pages to make it > clear that it's community contributed documentation etc. - might be worth > putting in the contributors block. "All documentation is contributed by > volunteers and may not have been checked for accuracy" something like that. > > > I'm kind of just wondering aloud here, but isn't it pretty obvious that > Drupal is entirely a community-driven, volunteer-run project, and that *all* > of its code/documentation has come from volunteers and may not have been > checked for accuracy? > > I can see that there's certainly a fine line to walk here, but since any > d.o user account can add a new handbook page, I would imagine that it's > pretty self-evident where the documentation comes from. > > So as not to be nothing but a dissenter, what about this idea: rather than > blanket the entire handbook with a big disclaimer, why not develop a set of > standard snippets that we as doc team members can add to pages we feel are > dangerous, risky, or need any other kind of red-flag placed on them. I'm > thinking something along the lines of Wikipedia's "The community feels that > this article might need revision?" sort of things. See any of the massive > list of template messages at > > http://en.wikipedia.org/wiki/Wikipedia:Template_messages > > for examples. Currently, it seems to me that the docs team does do this, > but we do this by submitting issues against certain nodes, which are not > visible from the handbook pages themselves and thus no user browsing the > handbook pages would see them. Using something akin to Wikipedia's template > messages system (which is purely enforced by convention, not by the > software?which is sensible if you ask me), would remedy that problem. > > Of course, I have no idea what the technical implementation of that would > look like. Just brainstorming here. > > Cheers, > -- > -Meitar Moscovitz > Personal: http://maymay.net > Professional: http://MeitarMoscovitz.com > > For example, code snippets probably need this more than most. > > http://drupal.org/handbook/customization/snippets - has a disclaimer > http://drupal.org/node/45471 - (theme snippets parent) has a disclaimer > http://drupal.org/node/35728 - an actual code snippet, doesn't have a > disclaimer. Unless I find the snippet via the handbook hierarchy (and IMO > more people will find it from incoming links, irc, google and drupal.orgsearch than clicking through), I won't see the disclaimer. > > If the block happens, then it's just an extra sentence to add, but it'd > need to be carefully worded - since equally we don't want to give the idea > that there's official, non-volunteer documentation hiding somewhere. > > Nat > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > > > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Fernando P. Garc?a, http://www.develcuy.com Developer - Analista de Sistemas +51 1 9 8991 7871, Mz. P Lt. 30 1et Urb. Pachacamac - VES, Lima - Per? -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/797ed19e/attachment.htm From Greg at GrowingVentureSolutions.com Thu Jun 5 15:23:44 2008 From: Greg at GrowingVentureSolutions.com (Greg Knaddison - GVS) Date: Thu, 5 Jun 2008 08:23:44 -0700 Subject: [documentation] Add disclaimer to all handbook pages In-Reply-To: <5ba75e2f0806050745t75ab2c1sa4694d0baaba71fd@mail.gmail.com> References: <5B2E5B8E-E489-497A-A95A-913E78F6EF4F@gmail.com> <5ba75e2f0806050745t75ab2c1sa4694d0baaba71fd@mail.gmail.com> Message-ID: <3861c6770806050823v3748f7fcn4eb12f59420db14c@mail.gmail.com> On Thu, Jun 5, 2008 at 7:45 AM, Fernando P. Garc?a wrote: > I agree with Nathaniel, Disclaimer makes sense, but may this concern Drupal > Association? So I just request this but can't provide any idea to solve this > polemic issue. This doesn't seem like an issue for the Drupal Association. The DA, in general, works on issues which can't be solved in the community directly. I'd say this is something that can be decided on this list. My 2 cents on a disclaimer - perhaps it could be part of an overall "contribute to the handbooks" block like: "The handbooks are based on user-contributed documentation and may not be completely accurate. You can help make them better by joining the documentation team." That way we get the message across without focusing on it too much. Regards, Greg -- Greg Knaddison Denver, CO | http://knaddison.com World Spanish Tour | http://wanderlusting.org/user/greg From catch56 at googlemail.com Thu Jun 5 15:32:41 2008 From: catch56 at googlemail.com (Nathaniel Catchpole) Date: Thu, 5 Jun 2008 16:32:41 +0100 Subject: [documentation] Add disclaimer to all handbook pages In-Reply-To: <3861c6770806050823v3748f7fcn4eb12f59420db14c@mail.gmail.com> References: <5B2E5B8E-E489-497A-A95A-913E78F6EF4F@gmail.com> <5ba75e2f0806050745t75ab2c1sa4694d0baaba71fd@mail.gmail.com> <3861c6770806050823v3748f7fcn4eb12f59420db14c@mail.gmail.com> Message-ID: On 6/5/08, Greg Knaddison - GVS > > > My 2 cents on a disclaimer - perhaps it could be part of an overall > "contribute to the handbooks" block like: > > "The handbooks are based on user-contributed documentation and may not > be completely accurate. You can help make them better by joining the > documentation team." > > That way we get the message across without focusing on it too much. > > > > Sounds about right to me. -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/622fb450/attachment.htm From sean at practicalweb.co.uk Thu Jun 5 15:41:37 2008 From: sean at practicalweb.co.uk (Sean Burlington) Date: Thu, 05 Jun 2008 16:41:37 +0100 Subject: [documentation] Add disclaimer to all handbook pages In-Reply-To: <3861c6770806050823v3748f7fcn4eb12f59420db14c@mail.gmail.com> References: <5B2E5B8E-E489-497A-A95A-913E78F6EF4F@gmail.com> <5ba75e2f0806050745t75ab2c1sa4694d0baaba71fd@mail.gmail.com> <3861c6770806050823v3748f7fcn4eb12f59420db14c@mail.gmail.com> Message-ID: <48480931.2070608@practicalweb.co.uk> Greg Knaddison - GVS wrote: > "The handbooks are based on user-contributed documentation and may not > be completely accurate. You can help make them better by joining the > documentation team." > I'm uncomfortable with the possible conclusion people may draw from this sort of suggestion. It's too close to the usual criticism of open source projects I quite like the wikipedia disclaimer http://en.wikipedia.org/wiki/Wikipedia:General_disclaimer It's more of a legal document - while at the same time giving the reader an understanding of the process. I'd suggest going further; emphasising the many benefits of community documentation - while acknowledging the limitations - and stating an intent to continually improve processes. In my view this issue is better dealt with by linking to full page - than trying to sum it up in a sentence. -- Sean Burlington www.practicalweb.co.uk From sepeck at gmail.com Thu Jun 5 15:42:48 2008 From: sepeck at gmail.com (Steven Peck) Date: Thu, 5 Jun 2008 08:42:48 -0700 Subject: [documentation] Add disclaimer to all handbook pages In-Reply-To: References: Message-ID: On Thu, Jun 5, 2008 at 3:01 AM, Nathaniel Catchpole wrote: > Whilst thinking about the contributors block and last updated info, it > occurred to me we don't have a disclaimer displayed for all handbook pages. > I think it'd make sense to have something displayed on all pages to make it > clear that it's community contributed documentation etc. - might be worth > putting in the contributors block. "All documentation is contributed by > volunteers and may not have been checked for accuracy" something like that. > > For example, code snippets probably need this more than most. > > http://drupal.org/handbook/customization/snippets - has a disclaimer > http://drupal.org/node/45471 - (theme snippets parent) has a disclaimer > http://drupal.org/node/35728 - an actual code snippet, doesn't have a > disclaimer. Unless I find the snippet via the handbook hierarchy (and IMO > more people will find it from incoming links, irc, google and drupal.org > search than clicking through), I won't see the disclaimer. > > If the block happens, then it's just an extra sentence to add, but it'd need > to be carefully worded - since equally we don't want to give the idea that > there's official, non-volunteer documentation hiding somewhere. > > Nat > > Historically the text is there because there was concern that anything in the handbook would be seen as 'OFFICIAL' and 'SAFE' which it is not official or safe. It's there because people contributed it. It's not that it's unsafe or unofficial it's that it's just something someone contributed and solved there problem. I don't really see a need to go overboard in yet more warnings/disclaimers. While we have unpublished unsafe, exploitable code as people came across it we do not have a formal review policy because there is not have enough knowledgeable people for such. (plus that would upset the people who believe that filters are inherently evil and I'd get more email :) I'd rather see a more generic testing and approach page for how/when to use snippets or bits and pieces as opposed to writing a module. Of course, things like that are very hard to write for the diverse skill levels and audiences we have. Also, on all the pages, we have the CC license block. I have to catch up on the block text issue in the queue this weekend when I am not on call. Steven Peck http://www.blkmtn.org From sepeck at gmail.com Thu Jun 5 16:03:51 2008 From: sepeck at gmail.com (Steven Peck) Date: Thu, 5 Jun 2008 09:03:51 -0700 Subject: [documentation] 'Last updated' information on handbook pages? In-Reply-To: <9f68efb70806050628u3d906f77wac22b59ca54f162c@mail.gmail.com> References: <68548D2B-A18F-4FDD-8FD5-D4367F110943@gmail.com> <9f68efb70806050628u3d906f77wac22b59ca54f162c@mail.gmail.com> Message-ID: It's a theme issue. As it stands now to enable it would also put author names and other information in that space. I will make a note for the eventual d.o. redesign but there are a lot of proposed changes right now and I generally don't like to do to many at once. Doing to many changes at once makes it difficult to evaluate effectiveness. Steven Peck http://www.blkmtn.org On Thu, Jun 5, 2008 at 6:28 AM, Shai Gluskin wrote: > I agree with Nat and Meitar, > > That time stamp is a data point. From reading the NYTimes to Wikipedia to > Drupal.org a reader is obligated to assess the value/limitations of any > particular piece of information. I think it is paternalistic to keep > information out of folks hands because of a possibility that some folks > might misinterpret the meaning of it. > > Reasons not to show information: > * causes usability problems by mucking up presentation or page clarity. > * takes up valuable system resources like running an "expensive" query. > > As long as it passes these tests, I'd be in favor. > > Shai > > On Thu, Jun 5, 2008 at 5:08 AM, Nathaniel Catchpole > wrote: >> >> I agree with Meitar. I don't think having recently updated timestamps on >> out of date information is going to lull people into a false sense of >> security - at least not compared to now, where they appear pretty much >> timeless except for the version taxonomy. >> >> This came up specifically in the case of module comparisons - if I see >> that a page comparing modules hasn't been updated for 6 months, then >> hopefully it'll indicate that things might have changed since then and >> encourage me to update it. At the moment, I have no idea either way unless I >> check the revisions tab (and I rarely do this unless I'm about to archive a >> page or make a big edit, hardly ever if I'm actually reading documentation). >> >> Also, if I see a page that hasn't been updated since 2006 or something, >> then it's an extra bit of encouragement to jump in and fix it. >> >> Nat >> >> -- >> Pending work: http://drupal.org/project/issues/documentation/ >> List archives: http://lists.drupal.org/pipermail/documentation/ > > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > From fernando at develcuy.com Thu Jun 5 16:29:45 2008 From: fernando at develcuy.com (=?UTF-8?Q?Fernando_P._Garc=C3=ADa?=) Date: Thu, 5 Jun 2008 11:29:45 -0500 Subject: [documentation] 'Last updated' information on handbook pages? In-Reply-To: <9f68efb70806050628u3d906f77wac22b59ca54f162c@mail.gmail.com> References: <68548D2B-A18F-4FDD-8FD5-D4367F110943@gmail.com> <9f68efb70806050628u3d906f77wac22b59ca54f162c@mail.gmail.com> Message-ID: <5ba75e2f0806050929l4e7eb685vb70642df426d193a@mail.gmail.com> I don't agree to have Timestamp because is inaccurate, but I agree to have a CCK field named: "Last update", with description like "Please modify this field only if you updated this content, It does not concerns typos and styling". Blessings! On Thu, Jun 5, 2008 at 8:28 AM, Shai Gluskin wrote: > I agree with Nat and Meitar, > > That time stamp is a data point. From reading the NYTimes to Wikipedia to > Drupal.org a reader is obligated to assess the value/limitations of any > particular piece of information. I think it is paternalistic to keep > information out of folks hands because of a possibility that some folks > might misinterpret the meaning of it. > > Reasons not to show information: > * causes usability problems by mucking up presentation or page clarity. > * takes up valuable system resources like running an "expensive" query. > > As long as it passes these tests, I'd be in favor. > > Shai > > On Thu, Jun 5, 2008 at 5:08 AM, Nathaniel Catchpole < > catch56 at googlemail.com> wrote: > >> I agree with Meitar. I don't think having recently updated timestamps on >> out of date information is going to lull people into a false sense of >> security - at least not compared to now, where they appear pretty much >> timeless except for the version taxonomy. >> >> This came up specifically in the case of module comparisons - if I see >> that a page comparing modules hasn't been updated for 6 months, then >> hopefully it'll indicate that things might have changed since then and >> encourage me to update it. At the moment, I have no idea either way unless I >> check the revisions tab (and I rarely do this unless I'm about to archive a >> page or make a big edit, hardly ever if I'm actually reading documentation). >> >> Also, if I see a page that hasn't been updated since 2006 or something, >> then it's an extra bit of encouragement to jump in and fix it. >> >> Nat >> >> -- >> Pending work: http://drupal.org/project/issues/documentation/ >> List archives: http://lists.drupal.org/pipermail/documentation/ >> > > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Fernando P. Garc?a, http://www.develcuy.com Developer - Analista de Sistemas +51 1 9 8991 7871, Mz. P Lt. 30 1et Urb. Pachacamac - VES, Lima - Per? -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/688faf7d/attachment.htm From sepeck at gmail.com Thu Jun 5 16:40:41 2008 From: sepeck at gmail.com (Steven Peck) Date: Thu, 5 Jun 2008 09:40:41 -0700 Subject: [documentation] 'Last updated' information on handbook pages? In-Reply-To: <5ba75e2f0806050929l4e7eb685vb70642df426d193a@mail.gmail.com> References: <68548D2B-A18F-4FDD-8FD5-D4367F110943@gmail.com> <9f68efb70806050628u3d906f77wac22b59ca54f162c@mail.gmail.com> <5ba75e2f0806050929l4e7eb685vb70642df426d193a@mail.gmail.com> Message-ID: Book pages are not CCK type, CCK is not on Drupal.org at this time. On Thu, Jun 5, 2008 at 9:29 AM, Fernando P. Garc?a wrote: > I don't agree to have Timestamp because is inaccurate, but I agree to have a > CCK field named: "Last update", with description like "Please modify this > field only if you updated this content, It does not concerns typos and > styling". > > Blessings! > > On Thu, Jun 5, 2008 at 8:28 AM, Shai Gluskin wrote: >> >> I agree with Nat and Meitar, >> >> That time stamp is a data point. From reading the NYTimes to Wikipedia to >> Drupal.org a reader is obligated to assess the value/limitations of any >> particular piece of information. I think it is paternalistic to keep >> information out of folks hands because of a possibility that some folks >> might misinterpret the meaning of it. >> >> Reasons not to show information: >> * causes usability problems by mucking up presentation or page clarity. >> * takes up valuable system resources like running an "expensive" query. >> >> As long as it passes these tests, I'd be in favor. >> >> Shai >> >> On Thu, Jun 5, 2008 at 5:08 AM, Nathaniel Catchpole >> wrote: >>> >>> I agree with Meitar. I don't think having recently updated timestamps on >>> out of date information is going to lull people into a false sense of >>> security - at least not compared to now, where they appear pretty much >>> timeless except for the version taxonomy. >>> >>> This came up specifically in the case of module comparisons - if I see >>> that a page comparing modules hasn't been updated for 6 months, then >>> hopefully it'll indicate that things might have changed since then and >>> encourage me to update it. At the moment, I have no idea either way unless I >>> check the revisions tab (and I rarely do this unless I'm about to archive a >>> page or make a big edit, hardly ever if I'm actually reading documentation). >>> >>> Also, if I see a page that hasn't been updated since 2006 or something, >>> then it's an extra bit of encouragement to jump in and fix it. >>> >>> Nat >>> >>> -- >>> Pending work: http://drupal.org/project/issues/documentation/ >>> List archives: http://lists.drupal.org/pipermail/documentation/ >> >> >> -- >> Pending work: http://drupal.org/project/issues/documentation/ >> List archives: http://lists.drupal.org/pipermail/documentation/ > > > > -- > Fernando P. Garc?a, http://www.develcuy.com > Developer - Analista de Sistemas > +51 1 9 8991 7871, Mz. P Lt. 30 1et Urb. Pachacamac - VES, Lima - Per? > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > From fernando at develcuy.com Thu Jun 5 16:49:01 2008 From: fernando at develcuy.com (=?UTF-8?Q?Fernando_P._Garc=C3=ADa?=) Date: Thu, 5 Jun 2008 11:49:01 -0500 Subject: [documentation] 'Last updated' information on handbook pages? In-Reply-To: References: <68548D2B-A18F-4FDD-8FD5-D4367F110943@gmail.com> <9f68efb70806050628u3d906f77wac22b59ca54f162c@mail.gmail.com> <5ba75e2f0806050929l4e7eb685vb70642df426d193a@mail.gmail.com> Message-ID: <5ba75e2f0806050949k1b6f439ehd0a357bc326a1611@mail.gmail.com> Ok, but at least it should be included in the body. Look at: http://tldp.org/HOWTO/Text-Terminal-HOWTO.html, they preserve a version and a date of reference. Some are more specific: http://tldp.org/HOWTO/Linux+WinNT.html Blessings! On Thu, Jun 5, 2008 at 11:40 AM, Steven Peck wrote: > Book pages are not CCK type, CCK is not on Drupal.org at this time. > > On Thu, Jun 5, 2008 at 9:29 AM, Fernando P. Garc?a > wrote: > > I don't agree to have Timestamp because is inaccurate, but I agree to > have a > > CCK field named: "Last update", with description like "Please modify this > > field only if you updated this content, It does not concerns typos and > > styling". > > > > Blessings! > > > > On Thu, Jun 5, 2008 at 8:28 AM, Shai Gluskin > wrote: > >> > >> I agree with Nat and Meitar, > >> > >> That time stamp is a data point. From reading the NYTimes to Wikipedia > to > >> Drupal.org a reader is obligated to assess the value/limitations of any > >> particular piece of information. I think it is paternalistic to keep > >> information out of folks hands because of a possibility that some folks > >> might misinterpret the meaning of it. > >> > >> Reasons not to show information: > >> * causes usability problems by mucking up presentation or page clarity. > >> * takes up valuable system resources like running an "expensive" query. > >> > >> As long as it passes these tests, I'd be in favor. > >> > >> Shai > >> > >> On Thu, Jun 5, 2008 at 5:08 AM, Nathaniel Catchpole > >> wrote: > >>> > >>> I agree with Meitar. I don't think having recently updated timestamps > on > >>> out of date information is going to lull people into a false sense of > >>> security - at least not compared to now, where they appear pretty much > >>> timeless except for the version taxonomy. > >>> > >>> This came up specifically in the case of module comparisons - if I see > >>> that a page comparing modules hasn't been updated for 6 months, then > >>> hopefully it'll indicate that things might have changed since then and > >>> encourage me to update it. At the moment, I have no idea either way > unless I > >>> check the revisions tab (and I rarely do this unless I'm about to > archive a > >>> page or make a big edit, hardly ever if I'm actually reading > documentation). > >>> > >>> Also, if I see a page that hasn't been updated since 2006 or something, > >>> then it's an extra bit of encouragement to jump in and fix it. > >>> > >>> Nat > >>> > >>> -- > >>> Pending work: http://drupal.org/project/issues/documentation/ > >>> List archives: http://lists.drupal.org/pipermail/documentation/ > >> > >> > >> -- > >> Pending work: http://drupal.org/project/issues/documentation/ > >> List archives: http://lists.drupal.org/pipermail/documentation/ > > > > > > > > -- > > Fernando P. Garc?a, http://www.develcuy.com > > Developer - Analista de Sistemas > > +51 1 9 8991 7871, Mz. P Lt. 30 1et Urb. Pachacamac - VES, Lima - Per? > > > > -- > > Pending work: http://drupal.org/project/issues/documentation/ > > List archives: http://lists.drupal.org/pipermail/documentation/ > > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -- Fernando P. Garc?a, http://www.develcuy.com Developer - Analista de Sistemas +51 1 9 8991 7871, Mz. P Lt. 30 1et Urb. Pachacamac - VES, Lima - Per? -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.drupal.org/pipermail/documentation/attachments/20080605/efe7f53d/attachment-0001.htm From darthsteven at gmail.com Thu Jun 5 21:07:58 2008 From: darthsteven at gmail.com (Steven Jones) Date: Thu, 5 Jun 2008 22:07:58 +0100 Subject: [documentation] 'Last updated' information on handbook pages? In-Reply-To: References: <68548D2B-A18F-4FDD-8FD5-D4367F110943@gmail.com> <9f68efb70806050628u3d906f77wac22b59ca54f162c@mail.gmail.com> Message-ID: > It's a theme issue. As it stands now to enable it would also put > author names and other information in that space. I will make a note > for the eventual d.o. redesign but there are a lot of proposed changes > right now and I generally don't like to do to many at once. Doing to > many changes at once makes it difficult to evaluate effectiveness. Seriously, I could add the date in about a minute. Not a valid reason. Not sure where the date would go in the theme though. Should it go in the header or at the bottom of the content? On Thu, Jun 5, 2008 at 5:03 PM, Steven Peck wrote: > > It's a theme issue. As it stands now to enable it would also put > author names and other information in that space. I will make a note > for the eventual d.o. redesign but there are a lot of proposed changes > right now and I generally don't like to do to many at once. Doing to > many changes at once makes it difficult to evaluate effectiveness. > > Steven Peck > http://www.blkmtn.org > > On Thu, Jun 5, 2008 at 6:28 AM, Shai Gluskin wrote: > > I agree with Nat and Meitar, > > > > That time stamp is a data point. From reading the NYTimes to Wikipedia to > > Drupal.org a reader is obligated to assess the value/limitations of any > > particular piece of information. I think it is paternalistic to keep > > information out of folks hands because of a possibility that some folks > > might misinterpret the meaning of it. > > > > Reasons not to show information: > > * causes usability problems by mucking up presentation or page clarity. > > * takes up valuable system resources like running an "expensive" query. > > > > As long as it passes these tests, I'd be in favor. > > > > Shai > > > > On Thu, Jun 5, 2008 at 5:08 AM, Nathaniel Catchpole > > wrote: > >> > >> I agree with Meitar. I don't think having recently updated timestamps on > >> out of date information is going to lull people into a false sense of > >> security - at least not compared to now, where they appear pretty much > >> timeless except for the version taxonomy. > >> > >> This came up specifically in the case of module comparisons - if I see > >> that a page comparing modules hasn't been updated for 6 months, then > >> hopefully it'll indicate that things might have changed since then and > >> encourage me to update it. At the moment, I have no idea either way unless I > >> check the revisions tab (and I rarely do this unless I'm about to archive a > >> page or make a big edit, hardly ever if I'm actually reading documentation). > >> > >> Also, if I see a page that hasn't been updated since 2006 or something, > >> then it's an extra bit of encouragement to jump in and fix it. > >> > >> Nat > >> > >> -- > >> Pending work: http://drupal.org/project/issues/documentation/ > >> List archives: http://lists.drupal.org/pipermail/documentation/ > > > > > > -- > > Pending work: http://drupal.org/project/issues/documentation/ > > List archives: http://lists.drupal.org/pipermail/documentation/ > > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ -- Regards Steven Jones