Posted by arianek on September 15, 2010 at 8:05pm
A ping in #drupal-docs earlier has brought to my attention that the Docs style guide only applies to handbook and not explicitly to interface text in Drupal core/contrib.
I'd think it should apply so we get consistent text and grammar formatting Drupal-wide, but didn't want to make such a sweeping declaration without some consensus from the community at large.
Please pipe up here and if people seem to be in agreement, I'd like to change the title (the page isn't aliased just fyi) to "Style guide for Handbook and interface text". (And then alias it to /handbook/documentation/style - also, holy mackerel the other path aliases in this area are a mess.)
Bikeshed away... :)
Comments
Probably makes sense.... as
Probably makes sense.... as second tier. User interface text (in core) follows the UX principles and ideas of the usability team currently. I'm not sure where that is documented and whether it's documented at all, but the language and wording is basically much more focused/limited on the respective task at hand. I see the main difference in that documentation pages are rather written like pages of a book, while user interface text is not. (Module help pages may be comparable, but that's only a very small fraction of user interface text.)
Daniel F. Kudwien
netzstrategen
Makes sense
+1
Maybe...
...in Drupal 8. ;) Keep your paws off the core interface text until then! ;)
If there's interest in unifying these, the handbook style guide (which, afaik, pre-dates a lot of people here) should probably be revisited and compared with the UX team's user interface best practices that was developed more recently, during the course of Drupal 7's development.
There are aspects of user interface text that don't properly carry over to written documentation, and vice-versa, so I'm not sure it necessarily makes sense to combine them wholesale. We should probably aim for them to be as similar as possible where it makes sense, though.
There should be standards for
There should be standards for interface text. Where they are put is less important. Should they be part of UX, docs style guide or coding practice? I think the principles that should be followed may cross those boundaries. The guidelines in UX that webchick referenced may be the most detailed we have at this point, I'm not sure.
When doing the timezone support for D7, the following point came up: http://drupal.org/node/11077#comment-1081808 regarding interface text that was reused in more than one context. I haven't worked with D7 enough to know how widespread this kind of thing might remain, or if it is now a non-issue, but that seems to me the kind of UX issue that would cross into coding territory, and goes beyond what would be relevant for docs.
Hi Joe - The Handbook style
Hi Joe -
The Handbook style guide is far more detailed http://drupal.org/node/338208 but like Sun pointed out, it's also different types of guidelines. We can't really go about making changes to the D7 core UI text at this point (cause then webchick would have to kill us all) ;) so this is more of a long-term question...
Oh, yes, this is clearly a D8
Oh, yes, this is clearly a D8 issue, my discussion of the D7 UI text was more in terms of how many such UX issues remain. If many have already been cleaned up in D7, then putting such guidelines in place now is less important. If we have many such remaining UX issues, then it makes sense to put a priority on getting guidelines in place now (wherever those guidelines may be published), so that we are better positioned to get those fixes in from the very beginning as part of the D8 cycle.
This is something I would be interested in helping on. I think that both improving guidelines themselves, and finding applicable areas to apply those guidelines in core are great examples of areas where people who may be less comfortable or a bit intimidated with working on core can contribute.
IMO the time is now for
IMO the time is now for documenting and promoting theseguidelines, since contrib is being ported to D7. D7 UX will only be as good as contrib makes it. Clean and consistent UI text is a big part of this.
Great point Roy, I wasn't
Great point Roy, I wasn't even thinking about contrib...
Agreed - no reason to hold up
Agreed - no reason to hold up on the guidelines, I just meant that we don't need to try and do a last minute update of UI text on D7 core. ;)
Angie - thx, nobody in the
Angie - thx, nobody in the contrib channel knew where such a thing was. But the level of detail in it is really not comparable to what's in the Handbook styleguide... so I really would like to evaluate whether the two can be coordinated more -
Definitely fine to start applying in D8 - this particular person was contacting me regarding a contrib module and related to http://drupal.org/node/338208#relatedwords how to write "e-mail" (which is with hyphen most places, but they were trying to get an instance of "email" changed and needed a reference that it was the right way.
Sun - totally, I will have to find someone who's up on UI best practices to review with me, maybe there's some way to link the two up more obviously and standardize whatever's appropriate between the two.
From a quick scan the docs
From a quick scan the docs style guide is mostly about grammar and spelling rules, most of which directly applies for UI, too. The goals for both are very different though. UI (help) texts should only give enough of a hint for people to make a decision on the next step and always focus on user goals, whereas docs can (should?) be exhaustive and complete and dive into the why and how of things. http://drupal.org/node/501452 documents guidelines for UI text.
Seems it would make sense to review both, combine the parts that apply to both and have sub pages that focus on the specific differences for docs and ui?
That approach makes sense to
That approach makes sense to me as well - the "Screen text" section of the UI text guidelines certainly has some overlap with how the instructive writing in the Handbook is organized as well. It'd be ideal to merge it somehow so we don't have to make changes in 2 places when needs be. But otherwise it'd definitely be a good idea to make sure that they are as unified as possible, and that people know to look to the Handbook styleguide for specifics on grammar etc.
Any opinions on changing the Handbook page title to reflect the guidelines applying more generally?
At this moment that page
At this moment that page documents UI best practices. The page about writing UI texts is http://drupal.org/node/604342.
The audience for docs and the Drupal UI are not necessarily the same. The docs are for people who build sites using Drupal (developers, themers, site builders...). UI texts are for people who use Drupal (i.e. John Doe who wants to buy something from a Übercart webshop). Terminology should definitely be the same (logically), but parts of texts that are not specifically about Drupal don't have to follow the same writing standards.
I'm working on a suite of modules to review texts. One of the intended use cases is to apply the UI writing style guide to UI texts and see whether texts are written properly. The same setup (with a different style guide config) can be use to review handbook pages.
Hi Xano - appreciate the
Hi Xano - appreciate the input, would be great if you can add it to the issue so it doesn't get lost in g.d.o http://drupal.org/node/936382 Thanks!
filed an issue for this work
filed an issue for this work http://drupal.org/node/936382
venn diagram
Thanks for your input, everyone!
The intersection between UI and docs reqs does exist.
Users, including community members and content managers, would predominantly rely on UI ("advanced help, etc").
Others would be drawn to rely on docs ... but whom? Docs are available when the UI is not self-guiding.
There are many roles who would be relying on both UI and docs.... content editors, themers, tech support, qa/qc staff, devs, sysadmins, etc.
Each role falls somewhere between 'advanced help' and api.drupal.org.
Some docs are recipes, some tutorials, some references.... can we differentiate docs by intended audiences?
Also, listing skills prerequisite to using docs helps people know if they can trust their knowledge to then invest the time in the docs.
Feel free to disagree, as I learn more that way.
Jeremy Donson
Database and Systems Engineer
New York City