Improve Text Format Admin Description

This is the actual text:

"Use the list below to review the text formats available to each user role, to select a default text format, and to control the order of formats listed in the Text format fieldset. (The Text format fieldset is displayed below textareas when users with access to more than one text format create multi-line content.) The text format selected as Default is available to all users and, unless another format is selected, is applied to all content. All text formats are available to users in roles with the "administer filters" permission.

Since text formats, if available, are presented in the same order as the list below, it may be helpful to arrange the formats in descending order of your preference for their use. To change the order of an text format, grab a drag-and-drop handle under the Name column and drag to a new location in the list. (Grab a handle by clicking and holding the mouse while hovering over a handle icon.) Remember that your changes will not be saved until you click the Save changes button at the bottom of the page."

This was fun. Been able to cut it down to a third. A lot of things are described redundantly on the text format starting page and on the different sub-pages of a specific format, so need to look into this as well. In filter.module, a text for the "more help" link (help system) is provided, but the link does not show up. This might be a bug.

Patch is attached.

The last submitted patch failed testing.

Rerolled. Probably some issue with wrong single and double quotes.

We always use 'HTML', not "Html".
"You can add a new one by..." => "Add a new one by..."
"Define which user roles can use which text format; the default format is available to all users." ? That first clause feels like a sentence fragment, at the least, you have to read it several times to parse.

I'm not sure the security warning is useful here and will be difficult to do in a way that is applicable to all situations. In particular, it is not allowing too many tags that may be dangerous; it is more a danger caused by the specific tags that are allowed. Quantity of tags is not all that applicable. And, that last sentence regarding PHP code may not be applicable to a site that has not enabled that module.

All that said, though, there certainly is room for improvement.

What about something like:

Use the list below to review the text formats available to each user role, to select a default text format, and to control the order formats are listed in the Text format fieldset, The text format selected as default is available to all users and is applied to new posts unless the author chooses another available format. All text formats are available to users in roles with the "administer filters" permission.

I completely agree with your remarks, especially the warning about the danger of allowing certain tags. Probably this warning should be exactly in the place where a user can allow tags or maybe allow all tags, or a drupal message when he changes tag settings.

Whith your alternative proposal though I am not happy at all:
Having in mind a user that does not know what a text format is: you can mention it as often as you want, he just won't get it. What is a text format? Mentioning that the user can select another format he finds out when editing a post, and in a default setting authenticicated user cannot, he can just use filtered HTML. The administer filters permission - yes this is dangerous but again: does someone trying to get a hold of text formats need to know that?

Also you don't have to review: you just choose or set.

Maybe we should meet in IRC and discuss general strategies. Basically I feel like contradicting most changes, and I hate that ;)

What and who are we targeting at? Drupal offers a gazillion options. If we describe all of them, we confuse. Do we want to explain technical concepts? Are we targeting at not-so-technical administrators? At people that know Drupal well or at people who don't know it at all?

Also how do we archieve that everything is explained exactly in the place it is needed and not twice or three times all over the place.

Looking at the page without making any changes is "reviewing" the changes. That's a very necessary thing to do considering this page has security implications (you'd review this page to determine what roles have access to what formats, for instance).

This is an important page, and while it may be true that people don't understand text formats, not mentioning the phrase "text format" does not explain what they are, and actually makes it harder to find out. You don't know what to Google, for instance.

In my opinion, trying to "dumb down" a concept is the wrong way to go. That's kinda' what we saw with moving "Taxonomy" to "Category".

But, that said, yeah, it's very hard to really nail the audience we're aiming at here.

Well actually I have nailed it for myself (and write all the texts in this respect): People who do not know Drupal but may have some experience with other content management systems. In this I orient on the D7UX principles "Privilege the content creator" "Make the most frequent tasks easy" "Design for the 80%" a.s.o. you know them... :P
People who _are_ experienced won't read those texts.

Personally I have learned about _nothing_ about drupal from the help texts. I learned it from experience, recommendations, documentation, and the most from errors I made. So I guess the ones that read the text won't learn any concepts, but should get help how to use the page they're on.

What can I do on this page? Where do I start?
And maybe a very slight hint "What are blocks" or "What are text formats?" Though the only way to learn that is to experience it.

So the sentence: "Text formats control which HTML tags are allowed." was my shot at that.

FYI: the location for this is now

/admin/config/content/formats

We attempted to test this, but only scratched the surface. We found this text, in the larger context, is part of a work-flow that needs revision/changes.

- User is unclear what "text format" means in the title.

- On configuration page, there is a loss of the prior context

- "More information about text formats' /filter/tips is not styled the same, and is completely out of the context of 'Text Format' area.

- The link to more information should be on the start page, in addition to configuration page

- The listing of text formats "name" column- the word "name" confusing

Many of the problems with the initial text are also part of a wider issue with the work-flow of this task.

Good shot to user-test it, heather :)
As the text formats are very important and have a lot of subpages (with a lot more confusing texts) this will not be a quick one.

How do we get users to experience what text formats are? This is also hard on the blocks page, but if you put a block into another region, you might see an immediate effect.

With text formats it is different. The entire form is so confusing, and to actually configure a format, you have to click configure twice (!) the help texts have hardly a chance to be helpful without reworking the entire interface.

So maybe an example that shows what happens when you allow html tags or forbid them could do the trick? (could be very simple: "Allow the <img> tag to allow the user to insert images" and show what happens if allowed or not...

All the other controls only group around this.

Needless to say that only medium advanced users will be able to make sense of this page, so I think we do not need to adress people who do not know what html is - they won't be able to make use of it.

As I doubt we will rework all the forms for input formats for D7 maybe the focus should be on making the texts much shorter (as always) and not trying to explain too much, but get the user to try it out.

Maybe you want to iterate on the text by making suggestions?
Needs iteration anyway, as every issue and particulary core issues...

Rebecca and I initially thought we could 'fire through' a few of these long-neglected ui-text issues. But we realised it was a bit more than we could handle in the time we had. I wanted to contribute the notes in case they were of use.

But this was like pulling one string on a larger knot that needs unraveling.

I would like to sit down and try a user test again on this. In fact, I am preparing a proposal for a UX testing in Belfast 26-27 Sept: DrupalCamp Ireland. Talked with Yoroy who is advising me. Should be of use, I hope! We might be able to come up with some simple/effective things to ease some of the problems... (i hope :)

Can 'Text Format' be renamed to 'Text Display' since that is what people will need to understand when setting these?

As for the copy, how about:

"Text formats control which HTML tags can be used in a node once the content is saved. People creating content may need to use additional HTML tags; configure their role to use Full HTML if needed. Anonymous users should be restricted to Filtered HTML or plain text for security reasons.

If you want to create a custom text format, add a new one by clicking on 'Add text format' above. "

Edited: I removed references to PHP since it's not handled on this screen by default (admin needs to enable it first)

Taking this on to try out revising the patch as per comments.

Hi! So - my first post seems to have vanished - trying again.

I've created a new patch to reflect the conversation and lisarex's final suggestion - as well as with a few edits of my own. Please review and see if it meets all of our expectations.

People creating content may need to use additional HTML tags; configure their role to use Full HTML if needed.

We should not advice to switch to full HTML in this case for security reasons. It's best to either modify the set of allowed tags of the "Filtered HTML" filter at config/content/formats/1/configure or create a new filter with an extended set of allowed tags. It should be mentionned that the Full HTML filter, if granted to any role, should only be used for trusted users.

Anonymous users should be restricted to Filtered HTML or plain text for security reasons.

agreed.

Text formats do not only apply to nodes, but to any fieldable entity type in D7 (users, comments, terms...) and possibly more (in contrib), so the first sentence should be made more generic.

I agree that the current text on this page is a disaster and that it is very important to make it better :) I think the most recent rewrite definitely does that. Here are some comments, though:

1. "Anonymous users should be restricted to Filtered HTML or plain text for security reasons."

   I'd suggest something like "untrusted users" here. On most sites, anonymous users aren't the only ones who should be restricted (and theoretically, it's even possible to have a site where anonymous users are trusted, although that's probably the 0.01% use case).

2. Overall, I'm not sure we want so much detail about security specifics on this page. A general comment about security would definitely be good, but like a few people said above, this isn't the right page to go into details - you can't actually do anything dangerous from this page itself anyway. (In Drupal 6 you could via the horrendous "default" radio button, but in Drupal 7 that is now gone.)

   If you want to give people proper detailed warnings about security, the issue to look at is #275811: Warn about potentially insecure filter configurations. It is really, really, really, really important to get that into Drupal 7 - that allows us to (dynamically) detect exactly which text formats on the site are configured insecurely, and to provided specific information about what makes it insecure (e.g., "The HTML filter is configured to allow the following unsafe tags: <script>, <object>, etc").

   If you care about security warnings, please review that patch - time is short :) There is also a corresponding design issue at #618902: Design and implement a user interface for warning about insecure text formats that needs lots of help from UX folks to figure out exactly how best to present the information from that to the site administrator.

3. I think we need to retain at least some explanation of reordering text formats and why you would want to do that, since that's the main thing you can actually do while on this page.
4. "A new custom text format can be created by clicking the link below."
   
   For accessibility reasons, let's try to avoid the word "clicking" (even though it was there already)... and we don't need to say this sentence at all anymore anyway, since due to recent D7 changes, the "Add text format" link now (happily) appears right underneath the help text.

***

Putting it all together, here's a stab at what I'd suggest:

@ David Rothstein

Well done! That looks like a really good, clear and concise description. You've incorporated all considerations.

Thanks also for the heads-up about the two patches which need reviewing, (your point #2)

Dcor, you want to re-roll this?

I'll be glad to review it.

Great, thanks!

As long as I'm here now, I'll just roll it into a patch...

Applied the patch and it looks good to me!

Not bad.
Still, the race is on, who can do the shortest? :)

As the text format descriptons distribute across several pages, this offers a great opportunity: we can distribute the text across at least two pages: the start page that this issue deals with, and at least the next page, when you enter one text format.

So best to only give only the least bit of necessary information on this page. We can be more specific if a user clicks an input format and tries to edit it or tries to create a new one.
We tried to come to some kind of guidelines in Utrecht, which (I hope) the gist can be summarized as follows (compare http://drupal.org/node/504080#comment-2195588 and http://drupal.org/node/501452):

1) Be as short as possible
2) General pattern for the user: "What can I do here?"
3) _No_ explanation of technical concepts. This belongs into the help text and is linked on the page.

All this is intended to match the very short attention-span of a user (desperately?) browsing through the admin pages looking for something particular or just strolling around and wondering what wonders he may find.

Much talk, attached another try as patch, Screenshot here:

I deliberately only mention "HTML tags" even if you can do much more and allow even PHP. But targeting the 80% or say 92% use case... guess people wanna control Html.

Rerolled: corrected typo "confituration" to "configuration"

And changed "Text Formats" to "Text formats" to be in sync with page title.

@eigentor - I see you're trying to improve David's patch #22 according to the guidelines for UI best practice.

However, I am wary it might be too brief in this case.

This is the one location where a novice site admin can introduce serious security threats to their site, and the latest patch does not explain how this page works. (and it's not obvious, in my experience).

David's 4 points in #20 are very clear. I think we can hit on his 4 points, more concisely, without introducing further confusion.

The text on this page should refer mainly to the functionality of this page alone; should not try to explain text formats & filters in general; and should alert the user to the security threat clearly.

His point 3) is that we should explain the ordering of the formats on this page(!) I, um, for one had trouble with that.

And generally:
We do not need to tell the user to add formats, right below there is a link to add.

Also my other issues with patch #26...

They don't get referred to anywhere else as configuration sets. We should not introduce new language here. They are text formats (filter sets would have been nice, but it didn't happen). We do not need to define it in this case, as the user is learning this notion through the interface.

When someone clicks 'configure' the list of options is referred to as filters. I think it's important not to lose this language. Look to the existing, very clear, documentation on this. http://drupal.org/node/213156

The conceptual model of 'filter' fits here, as any text, code or string can be input and uploaded to the site. Yet the filter controls what is displayed or executed either on the server or client side.

So I'm giving this a roll...

Cute. I forgot how to make a patch.

I need tea.

Yeah, I agree with making it more concise. However:

• Like @heather said, we do indeed still want to explain what you can do on the page itself :) Sounds like we now have two suggestions:
  1. "When creating content, the available text formats will be presented in the order you arrange them below."
  2. "Arrange the order of text formats presented to your users, in descending order of preference for use. The default format for each user role is the first one on this list in which their role appears."

  The first one is shorter, and I still like it better... does it explain things well enough? I am not sure there is an advantage of using the term "default format" here anymore - IMO that is something of a relic of Drupal 6.

• The goal of adding a (meaningful) security warning might conflict with the goal of brevity. The only reason to add a security warning on this particular page is because they can review which roles have which formats - but with #618902: Design and implement a user interface for warning about insecure text formats we could explore the possibility of adding some kind of warning inline (in the table), only for the particular formats that are actually security risks - and therefore maybe not mentioning it in the help text at all. Not sure if there is a good way to do that which doesn't look repetitive, though.
• If we don't want to define "text formats" on this page, we shouldn't mention that they are made up of filters either - that is kind of a definition in disguise :) Also, you can do a fair amount of configuration of text formats in Drupal 7 without even knowing or caring that they are made up of filters.

  Given that this page is the main overview page for all text format administration (and that the overall "more help" page for the filter.module is a wall of text), I wonder if a one sentence definition is maybe still a good idea? If so, I'd prefer to aim for 100% here, not 80% :) Besides, stuff like Markdown and BBCode is (I'm guessing) much more common than 20% - typing HTML tags into a textarea is pretty old-school, and one of the main purposes of the text format system is to allow people to avoid that. We can probably remove the word "code", though... since if you can be trusted to type PHP code, you hopefully don't need the help text here :)

So, trying to put it all together again, I'd suggest maybe something like this:

If we're bold, delete the second sentence:

If we're really bold, delete the whole first paragraph :)

Here is another stab, quite similar to Davids first and longest proposal of #29.
I tried a bit more active wording. So rather say "Control the HTML" instead of "Text formats control the HTML" as it is clear that this is text formats: it is in the header of the page.

And rather than saying "They are central to a site's security, so untrusted users should be.." write "Don't allow too much formatting for untrusted users..." Also the "when creating content" of the third paragraph can be cut, for the user has to see that anyway and it is only when creating content.

Also added in a short encouragement to click the configure link next to a text format, since all the magic starts only after they click that link...

changed "securitity" to "security"

Tags in HTML Tags should be all lower case, i.e. HTML tags.

OK, like all the changes :) .. Fixed this minor issue pointed out by scor. Should be RTBC.

I changed "behaviour" to "behavior" (not sure if there is an official style guide for American vs British English, but "behavior" is what is used elsewhere in Drupal).

Otherwise, looks good. I think the "Don't allow too much formatting" phrasing is a little strange, but don't have any great ideas for anything better at the moment.... Maybe we can improve it later, depending on how other issues go.

A big improvement overall.

Regarding the last point: one try at rewording it. We want to try and not use "don'ts". Does it help to give examples of risky tags or is that a can of worms we don't want to open now?