Handbook placement of "Embedded documentation style guide"

This is a good idea. There should probably be at least some kind of guideline as to how much text to put on /admin/help pages and how much to leave to the handbook etc.

Comments against the handbook page is the most amount of work and least likely to be productive though. I think it's best to keep the discussion here and then get someone with permissions to edit the authoring page. Or we can just create a new handbook page for "help text style guide" if it takes a different direction, work in that, then move/merge later on.

I first submitted this to the Documentation queue. After further consideration, I'm moving it to the Drupal core queue, documentation component. Since this guide is related to potential core changes that are documentation related (as opposed to potential documentation changes that are core related), it seems as if it would fit better here.

I may well be wrong though. Anyone who feels strongly about where this belongs should please feel free to relocate it.

I'll try to work up a proposed style guide, building off the contents of http://drupal.org/about/authoring, as an example of what I'm envisioning here.

I am also up for writing a guide on writing proper translatable interfaces, which will coincide with some of the points you would have int this guide, so we should rather merge our efforts. However, I think this guide will not be in core, so I'd move this issue back to the documentation project.

The other issue about translatable interfaces guide, which might become a GHOP task: http://drupal.org/node/194962

Keith, excellent idea. I've added this issue to the list of Active usability projects. And I would like to help.

There are others on g.d.o/usability with a sense for clear writing style. Perhaps start a wiki page there?

My idea is to have a guide for module developers, explaining how to write help pages, how to write input field descriptions, how to choose the right labels on tabs, etc. I like the documentation guidelines setup with good and bad examples.

This is clearly the place to re-post my help-text-rewriting attempts. I fear this will be my only addition for a while, but I will join you in January for D7. See Attachment. Here is the link: http://limmertime.de/Dateien/drupal/menu-compare-1.jpg
(also attached)
My main objective was to shorten help texts to gain space cause they bloat the UI when you try to shorten input and admin forms. At the same time they also get more concise (hehe Webchicks comment about the old book-content-type description: "A book is an effort. Er...." )Let me guide you to the hilarious humour in spite of hard fate of Phil: http://webchick.net/contributor-spotlight/keith-smith

Right on, eigentor, this is exactly what I meant. A lot of help texts / descriptions / whatever you call them are way too wordy. In your example not only are they more concise, they are more clear.

The page I was casting about for, but did not find in an initial search, is "Embedded documentation style guide", at http://drupal.org/node/24566. In it, there are clear and detailed instructions for writing internal help text. It is therefore unfortunate that I didn't read it, before altering a lot of the internal help texts. :)

That said, actually there is very very little here that conflicts. The style guide specifies "2 paragraphs and a list of links" and we've gone over that in a lot of instances. It specifies the format of "The phrase "For more information, read the configuration and customization handbook modulename page" should be automatically added to the administration help when these pages are extracted from the handbook and added to the module code.", and I have a patch somewhere proposing to alter that, so I'll link to this section in that issue.

We've not been doing some of the links to internal system paths as this document describes, but we can look at that also, and either amend the specification or correct the text.

All in all, though, no big problems, and I'm glad to find this document. I've got a number of changes I'd like to propose to *it*, but that is best handled in another issue.

I'm not sure whether this is best marked won't fix, duplicate, or fixed. I'm going to go with fixed, as it actually is, in so much as the document existed before I created the issue.

Great that there's a handbook page on this :) There's just one thing that hit me - why has it been placed in "About Drupal documentation > Contributing to documentation"? I think it would be much easier to find these important guidelines if they were placed in Module developer's guide, or at least provide a link from that guide.

I've set this issue to "needs review" so that this can be discussed.

I'm going to move this issue over to the Documentation queue, since the point has been raised, in #9, about the placement of http://drupal.org/node/24566.

Retitling.

Easier to find for who? If we scatter stuff about documentation all over the place then how will people looking for documentation stuff find it? Buried in the module section?

Perhaps in the landing page on module development a link to the page could be added?

I was thinking of contrib module developers such as myself, who will most likely write an entry in admin/help for their modules. It looks as though the style guide was intended for the documentation team, but I think module developers will find it useful as well.

I found an appropriate place in the Module developer's guide to link to this node from, and since I'm a member of the documentation team, I went ahead and edited it in. See http://drupal.org/node/161085 under Use hook_help..

Setting this as fixed.

Automatically closed -- issue fixed for two weeks with no activity.