From drupal-documentation at nederdev.nl Sat Jun 6 08:35:21 2009 From: drupal-documentation at nederdev.nl (Bart Feenstra) Date: Sat, 6 Jun 2009 10:35:21 +0200 Subject: [documentation] Text guidelines Message-ID: <2333086B-1274-4961-B90F-AA787FA7DD16@nederdev.nl> Hi all! The last weeks I have been busy working on UX stuff in Drupal. Part of the work I've done is rewrite texts - or remove them. A lot of texts in both core and contrib are unnecessary, too complicated and long or add redundant information to pages. I am working on http://drupal.org/project/atr to automatically review texts used in the code (it will be able to review translations in the near future). Plans are to set it up on t.d.o when it's done and make it create text reviews of patches, like SimpleTest already tests patches, and existing code. At this moment ATR checks for strings that contain blacklisted words and strings that are similar. I assume the idea behind a blacklist is known to all of you. The similarity check is intended to prevent (near) duplicate text from being used to improve consistency and decrease efforts needed to translate Drupal (Less _is_ more in this case). I want to create a handbook page containing guidelines for developers on writing texts. Proposals: - Avoid certain words or phrases (the blacklist, yet to be determined). - Prevent duplicate texts (the similarity check). - Don't use subordinate clauses unless absolutely necessary. - Form element descriptions are no must. In most cases a title should be sufficient. If not, don't repeat the same thing the title explains to the user already. - Don't use terms like "Advanced options". These don't tell the user what it means, just that the writer thinks this stuff is rocket science. Unfortunately nobody can tell you if you're a scientist capable of this stuff until you actually view the options, rendering the label useless. - If you're not a native speaker of English, make sure your texts get reviewed by someone who is. If you are, do the same. - Don't tell users how they should use your stuff through the UI. Just tell them what it does. Background information and tips belong in the documentation (help texts, handbooks). Some guidelines may seem so simple that one would assume everybody knows about them. They don't. A lot of developers are great at programming cool stuff, but find it hard to write proper texts or make good UIs. This handbook page is intended as an easy reference for those people. Thanks for reading and please let me know what you think :) Bart Xano From yahgrp at poplarware.com Sun Jun 7 15:14:20 2009 From: yahgrp at poplarware.com (Jennifer Hodgdon) Date: Sun, 07 Jun 2009 08:14:20 -0700 Subject: [documentation] Text guidelines In-Reply-To: <2333086B-1274-4961-B90F-AA787FA7DD16@nederdev.nl> References: <2333086B-1274-4961-B90F-AA787FA7DD16@nederdev.nl> Message-ID: <4A2BD94C.4060601@poplarware.com> Hi Bart, These guidelines look pretty good to me, except possibly the last one -- and maybe it's just the wording: "Don't tell users how they should use your stuff through the UI. Just tell them what it does. Background information and tips belong in the documentation (help texts, handbooks)." People don't tend to read separate documentation, in my experience. So it seems to me that a sentence describing what to do at the top of the "Options" or "Setup" screen of a module can be helpful, and save people contacting the module maintainers for support. And putting short tips in the Description field is also useful. I do agree that lengthy descriptions belong in the main description, but maybe this guideline could be modified to say that concise tips have a place in the module itself? Just a thought... Anyway, this seems like a good idea, and I look forward to seeing the Handbook page (I am assuming you're planning to add it to the module developers guide?). I hope the Handbook page has some examples, with better alternatives proposed, as illustrations (especially for things like Advanced Options). Regards, Jennifer Bart Feenstra wrote (in part): > I want to create a handbook page containing guidelines for developers on > writing texts. Proposals: > - Avoid certain words or phrases (the blacklist, yet to be determined). > - Prevent duplicate texts (the similarity check). > - Don't use subordinate clauses unless absolutely necessary. > - Form element descriptions are no must. In most cases a title should be > sufficient. If not, don't repeat the same thing the title explains to > the user already. > - Don't use terms like "Advanced options". These don't tell the user > what it means, just that the writer thinks this stuff is rocket science. > Unfortunately nobody can tell you if you're a scientist capable of this > stuff until you actually view the options, rendering the label useless. > - If you're not a native speaker of English, make sure your texts get > reviewed by someone who is. If you are, do the same. > - Don't tell users how they should use your stuff through the UI. Just > tell them what it does. Background information and tips belong in the > documentation (help texts, handbooks). -- Jennifer Hodgdon * Poplar ProductivityWare www.poplarware.com Drupal, WordPress, and custom Web programming From drupal at rocktreesky.com Sun Jun 7 19:33:31 2009 From: drupal at rocktreesky.com (Addison Berry) Date: Sun, 7 Jun 2009 15:33:31 -0400 Subject: [documentation] Doc Roadmap IRC meeting June 16 References: <20090607193004.BD23B16B541@www1.drupal.org> Message-ID: <8A5BB24F-537A-4B26-AD83-1437AA719EE0@rocktreesky.com> > add1sun has posted a Event at http://groups.drupal.org/node/23017 > > Doc Roadmap IRC meeting > --------------- > It has been a while since we have had an IRC meeting. I will be > publishing a doc "roadmap" of a plan on how to tackle some of the > bigger doc issues sometime this week (June 7- 12). I'd like to give > folks time to digest it and then have an IRC meeting next week > (Tuesday, June 16) for people to discuss, raise questions, yell at > me, help organize, etc. I'm setting this meeting time in advance > rather than Doodle because I have a very intense travel schedule now > and so only have narrow windows that I can set aside for this. > > Tuesday, June 16 at 1 p.m. EDT (5 p.m. GMT) - find your timezone > here: http://www.timeanddate.com/worldclock/fixedtime.html?month=6&day=16&year=2009&hour=13&min=0&sec=0&p1=179 > > The "roadmap" will be posted to the front page of Drupal.org and an > email will go out to this list pointing to it as soon as it is up. - Addi From drupal-documentation at nederdev.nl Sun Jun 7 20:07:55 2009 From: drupal-documentation at nederdev.nl (Bart Feenstra) Date: Sun, 7 Jun 2009 22:07:55 +0200 Subject: [documentation] Text guidelines In-Reply-To: <4A2BD94C.4060601@poplarware.com> References: <2333086B-1274-4961-B90F-AA787FA7DD16@nederdev.nl> <4A2BD94C.4060601@poplarware.com> Message-ID: <85141D44-D2ED-4B78-B206-EF15B4C5C6E8@nederdev.nl> Hi Jennifer, My intentions were to prevent explanations like "Recommended for live sites" and more verbose texts of the same kind. Unless a certain option has serious implications such an explanation should not be necessary. I'm not yet sure where to add the handbook page. It is helpful to developers, but also to people who focus on UI stuff rather than writing texts. Suggestions about this are welcome :) Best regards, Bart On Jun 7, 2009, at 17:14, Jennifer Hodgdon wrote: > Hi Bart, > > These guidelines look pretty good to me, except possibly the last > one -- and maybe it's just the wording: > > "Don't tell users how they should use your stuff through the UI. Just > tell them what it does. Background information and tips belong in the > documentation (help texts, handbooks)." > > People don't tend to read separate documentation, in my experience. > So it seems to me that a sentence describing what to do at the top > of the "Options" or "Setup" screen of a module can be helpful, and > save people contacting the module maintainers for support. And > putting short tips in the Description field is also useful. I do > agree that lengthy descriptions belong in the main description, but > maybe this guideline could be modified to say that concise tips have > a place in the module itself? > > Just a thought... Anyway, this seems like a good idea, and I look > forward to seeing the Handbook page (I am assuming you're planning > to add it to the module developers guide?). I hope the Handbook page > has some examples, with better alternatives proposed, as > illustrations (especially for things like Advanced Options). > > Regards, > Jennifer > > Bart Feenstra wrote (in part): >> I want to create a handbook page containing guidelines for >> developers on writing texts. Proposals: >> - Avoid certain words or phrases (the blacklist, yet to be >> determined). >> - Prevent duplicate texts (the similarity check). >> - Don't use subordinate clauses unless absolutely necessary. >> - Form element descriptions are no must. In most cases a title >> should be sufficient. If not, don't repeat the same thing the title >> explains to the user already. >> - Don't use terms like "Advanced options". These don't tell the >> user what it means, just that the writer thinks this stuff is >> rocket science. Unfortunately nobody can tell you if you're a >> scientist capable of this stuff until you actually view the >> options, rendering the label useless. >> - If you're not a native speaker of English, make sure your texts >> get reviewed by someone who is. If you are, do the same. >> - Don't tell users how they should use your stuff through the UI. >> Just tell them what it does. Background information and tips belong >> in the documentation (help texts, handbooks). > > -- > Jennifer Hodgdon * Poplar ProductivityWare > www.poplarware.com > Drupal, WordPress, and custom Web programming > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ From stella at stellapower.net Sun Jun 7 22:19:05 2009 From: stella at stellapower.net (Stella Power) Date: Sun, 7 Jun 2009 23:19:05 +0100 Subject: [documentation] Text guidelines In-Reply-To: <2333086B-1274-4961-B90F-AA787FA7DD16@nederdev.nl> References: <2333086B-1274-4961-B90F-AA787FA7DD16@nederdev.nl> Message-ID: I wonder if this module should be added as part of the coder module. I admit I haven't looked at the code, so can't say how easy that would be. It's probably not realistic to add it to Drupal 6 version of coder, but may be possible for Drupal 7. Cheers, Stella On Sat, Jun 6, 2009 at 9:35 AM, Bart Feenstra < drupal-documentation at nederdev.nl> wrote: > Hi all! > > The last weeks I have been busy working on UX stuff in Drupal. Part of the > work I've done is rewrite texts - or remove them. A lot of texts in both > core and contrib are unnecessary, too complicated and long or add redundant > information to pages. I am working on http://drupal.org/project/atr to > automatically review texts used in the code (it will be able to review > translations in the near future). Plans are to set it up on t.d.o when it's > done and make it create text reviews of patches, like SimpleTest already > tests patches, and existing code. > > At this moment ATR checks for strings that contain blacklisted words and > strings that are similar. I assume the idea behind a blacklist is known to > all of you. The similarity check is intended to prevent (near) duplicate > text from being used to improve consistency and decrease efforts needed to > translate Drupal (Less _is_ more in this case). > > I want to create a handbook page containing guidelines for developers on > writing texts. Proposals: > - Avoid certain words or phrases (the blacklist, yet to be determined). > - Prevent duplicate texts (the similarity check). > - Don't use subordinate clauses unless absolutely necessary. > - Form element descriptions are no must. In most cases a title should be > sufficient. If not, don't repeat the same thing the title explains to the > user already. > - Don't use terms like "Advanced options". These don't tell the user what > it means, just that the writer thinks this stuff is rocket science. > Unfortunately nobody can tell you if you're a scientist capable of this > stuff until you actually view the options, rendering the label useless. > - If you're not a native speaker of English, make sure your texts get > reviewed by someone who is. If you are, do the same. > - Don't tell users how they should use your stuff through the UI. Just tell > them what it does. Background information and tips belong in the > documentation (help texts, handbooks). > > Some guidelines may seem so simple that one would assume everybody knows > about them. They don't. A lot of developers are great at programming cool > stuff, but find it hard to write proper texts or make good UIs. This > handbook page is intended as an easy reference for those people. > > Thanks for reading and please let me know what you think :) > > Bart > Xano > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ > -------------- next part -------------- An HTML attachment was scrubbed... URL: From yahgrp at poplarware.com Mon Jun 8 14:19:01 2009 From: yahgrp at poplarware.com (Jennifer Hodgdon) Date: Mon, 08 Jun 2009 07:19:01 -0700 Subject: [documentation] Text guidelines In-Reply-To: <85141D44-D2ED-4B78-B206-EF15B4C5C6E8@nederdev.nl> References: <2333086B-1274-4961-B90F-AA787FA7DD16@nederdev.nl> <4A2BD94C.4060601@poplarware.com> <85141D44-D2ED-4B78-B206-EF15B4C5C6E8@nederdev.nl> Message-ID: <4A2D1DD5.2030302@poplarware.com> My feeling is that it belongs in the module developers guide, but then if there is a section of the Handbook that deals with UI in general (or if someone creates one at a later date), you could always link from that section to this page as well. Or vice versa (put it in the UI section, if such a thing exists, and link from the module developers guide). You might also link to this page from the Documentation Style Guide pages, as many of your guidelines relate to writing style. --Jennifer Bart Feenstra wrote: > I'm not yet sure where to add the handbook page. It is helpful to > developers, but also to people who focus on UI stuff rather than writing > texts. Suggestions about this are welcome :) -- Jennifer Hodgdon * Poplar ProductivityWare www.poplarware.com Drupal, WordPress, and custom Web programming From drupal at rocktreesky.com Fri Jun 12 10:26:58 2009 From: drupal at rocktreesky.com (Addison Berry) Date: Fri, 12 Jun 2009 06:26:58 -0400 Subject: [documentation] Doc roadmap posted on d.o Message-ID: <389E2189-5EA2-4373-BE4D-EB5643363018@rocktreesky.com> Hello all, This is a little heads up that I have posted the draft docs "roadmap" I've been on about for a while now. It is on the Drupal.org front page. http://drupal.org/node/488070 Don't forget that we have an IRC meeting scheduled to talk about it on Tues., June 16 at 17:00 GMT. http://groups.drupal.org/node/23017 Thanks to everyone that helped us get this started! - Addi From drupal at rocktreesky.com Tue Jun 16 14:55:32 2009 From: drupal at rocktreesky.com (Addison Berry) Date: Tue, 16 Jun 2009 10:55:32 -0400 Subject: [documentation] Reminder: IRC meeting at 18:00 GMT Message-ID: Just a quick reminder that we'll have a meeting in IRC #drupal-docs channel on the Freenode network in two hours (1pm Eastern US, 18:00 GMT). We'll discuss the new roadmap doc (http://drupal.org/node/ 488070) and plan future meetings. http://groups.drupal.org/node/23017 - Addi From yahgrp at poplarware.com Thu Jun 18 16:45:28 2009 From: yahgrp at poplarware.com (Jennifer Hodgdon) Date: Thu, 18 Jun 2009 09:45:28 -0700 Subject: [documentation] Issue posted for contrib module information architecture Message-ID: <4A3A6F28.5050309@poplarware.com> I just posted an issue with thoughts about the information architecture for contrib modules -- more of a vision than a plan: http://drupal.org/node/495418 Comments welcome, of course. I also realize though that the ideas would impact more than just documentation... Not sure how to get it to the attention of others it might impact, such as d.o webmasters, redesign of d.o, etc., or if that is appropriate... ??? --Jennifer -- Jennifer Hodgdon * Poplar ProductivityWare www.poplarware.com Drupal, WordPress, and custom Web programming From drupal at rocktreesky.com Thu Jun 18 20:42:21 2009 From: drupal at rocktreesky.com (Addison Berry) Date: Thu, 18 Jun 2009 17:42:21 -0300 Subject: [documentation] June roadmap IRC meeting summary and log References: <20090618203111.B5BD816B553@www1.drupal.org> Message-ID: > add1sun has posted a Discussion at http://groups.drupal.org/node/23395 > > June roadmap IRC meeting summary and log > --------------- > This is a short summary of the IRC meeting we had on Tuesday, June > 16 to discuss the new roadmap that was posted last week, http://drupal.org/node/488070 > . Lots of folks showed up and we had a god chat. Unfortunately we > had to cut it off after an hour, but more meetings will be coming. > You can get the full deal by reading the IRC transcript: http://pastebin.com/f4ee1b70f > The main things that were discussed were around the question of what > this "content architecture" stuff is about. I'll reprint my best > effort response here (though Becca would be able to explain better > probably) and also note that the concern that we follow industry > standards as a guideline so that we aren't striking off on our own. > The superquick skinny on the architecture is that we need to > restructure how our content is presented to make it findable and > easier to use. This means not just the navigation but also > categories/tagging and looking at the structure of each page as well > as the overall structure. Becca is leading this up and is starting > to gather data about our content, users and community. We'll be > asking for help on this in the next few weeks. As we sift through > all of this stuff, Becca will come up with an "ideal" architecture > to start from. We will then continue poking and prodding, doing > cardsorts and testing until we feel we have a good arch to implement. > I also provided some clarification about the appendices that were > attached to the roadmap draft. Appendices A and B are a brain dump > of tasks that may be needed to accomplish our goals. At the Toronto > sprint we had time to brainstorm tasks but not fill out any details > or expand on them. Anyone that would like to dive into one of the > goals can just use the task table outlines as a place to start in > terms of figuring out what they need to consider and do. The > appendix C mindmap is an easier to digest overview of A and B. > I talked a bit about the Writing Open Source conf that I attended > and encouraged anyone interested to join the "wosdocs" community at http://writingopensource.com > . We then also moved to a very brief conversation about some > toolsets like docbook and DITA, though it was noted that we aren't > at a place to get into those details until the architecture is done. > We then ended up discussing the fact that the roadmap has two > priority goals right now (content architecture and recognition/ > rewards for contributors) but that if folks want to jump in on other > tasks that don't depend on those two, they can get started. We will > use the Community Inititives section to creating organizing pages, > but create issues for the actual tasks/work that needs to happen. > Feel free to email the mailing list to find others interested in > working on similar goals. > We wrapped up talking about a number of topics like single-sourcing > docs and Becca asked if anyone had any examples of good > documentation for something with a similar goal as Drupal. > Whew, OK, it was a lot of talking, which was awesome! If you haven't > taken the "thank you" survey on http://docs.drupaltest.org, please > do. I'd like to have at least two meetings in July: one for a status > report on the roadmap and another to begin our plan for Drupal 7 > documentation. I'm on the road right now, but I'll send Doodles out > for those meetings in the next week or so. - Addi -------------- next part -------------- An HTML attachment was scrubbed... URL: From drupal at rocktreesky.com Sat Jun 20 13:33:36 2009 From: drupal at rocktreesky.com (Addison Berry) Date: Sat, 20 Jun 2009 10:33:36 -0300 Subject: [documentation] Issue posted for contrib module information architecture In-Reply-To: <4A3A6F28.5050309@poplarware.com> References: <4A3A6F28.5050309@poplarware.com> Message-ID: <211B6E4F-60BF-4467-87F8-B308FEE8BF7A@rocktreesky.com> Jennifer, thanks for writing all of that out! I added a link from the redesign to the issue. We should definitely point to this from the main redesign group (http://groups.drupal.org/drupalorg-redesign-plan-drupal-association)and ferret out the webmaster issues that may exist around this as well. Again, awesome work and thank you. - Addi On Jun 18, 2009, at 1:45 PM, Jennifer Hodgdon wrote: > I just posted an issue with thoughts about the information > architecture for contrib modules -- more of a vision than a plan: > > http://drupal.org/node/495418 > > Comments welcome, of course. > > I also realize though that the ideas would impact more than just > documentation... Not sure how to get it to the attention of others > it might impact, such as d.o webmasters, redesign of d.o, etc., or > if that is appropriate... ??? > > --Jennifer > > -- > Jennifer Hodgdon * Poplar ProductivityWare > www.poplarware.com > Drupal, WordPress, and custom Web programming > > -- > Pending work: http://drupal.org/project/issues/documentation/ > List archives: http://lists.drupal.org/pipermail/documentation/ From drupal at rocktreesky.com Sun Jun 28 12:55:46 2009 From: drupal at rocktreesky.com (Addison Berry) Date: Sun, 28 Jun 2009 09:55:46 -0300 Subject: [documentation] Schedule next IRC meeting re: Drupal 7 References: <20090628023006.578D516B4E5@www1.drupal.org> Message-ID: <62733156-3462-4A6B-889A-17FF57F9631E@rocktreesky.com> > add1sun has posted a Discussion at http://groups.drupal.org/node/23698 > > Schedule next IRC meeting re: Drupal 7 > --------------- > We need to start thinking out our plan for making sure that Drupal 7 > has at least basic getting started documentation written when it is > released. We'll meet for an hour in #drupal-docs on the Freenode > network to talk about what we need to do and see if we can come up > with some target dates. > Please fill out the Doodle (http://www.doodle.com/d76k62as22hs889k) > by this Thursday, July 2, so we can set a time for the meeting. - Addi