[drupal-docs] usability of "Avoid all embedded headings"

[Djun Kim]

By all means, let's expand and clarify the
"Avoid all embedded headings" page.

Let's also get Steven's patch to fix up
embedded headers on-the-fly into
book module ASAP, for those rare cases
where it makes sense to embed an header.

But let's make it clear to authors and editors
that this practice should be avoided in almost all
cases.

Djun

On 3 Jun 2005, at 1:08 PM, Charlie Lowe wrote:

> There is no doubt that breaking up the longer help texts in many ways
> has created a more usable handbook. However, that does not mean that 
> the
> prevous "debate" addressed all of the usability concerns with how
> strongly to discourage headings. If we are to "strongly discourage"
> headings, then we have to provide guidelines that addresss those
> usability issues. And we need to figure out where they are not 
> "strongly
> discouraged" rather than applying a blanket statement which provides no
> instance of where they might be used properly. For instance, I would
> find the Morke/Nielsen text much less reader friendly if it was broken
> up into 40+ pages based upon the headings as they currently are in that
> text than if it was broken up into fewer main sections.
>
> Plus, some of the reasons on the "Avoid all embedded headings" are no
> longer valid, inaccurate, or unclear.
>
> - "It will be impossible for others to add or re-arrange sections 
> unless
> they have edit permissions for a page." We now have plenty of people
> with edit permissions on the entire handbook.
>
> - "Your page is too long. If readers need to scroll through a long 
> page,
> they will probably need the navigational clues that headings provide -
> but they will in all cases be better served by having the page divided
> into true subsections via child nodes." I'm not convinced this is 
> always
> the case.
>
> - "You are trying to achieve visual impact. Visual impact is OK, though
> it's often not done well. If you must, do it with style (pun 
> intended)."
> It's not clear to me what visual impact is. Perhaps examples of where 
> it
> is not done well and where it is done well would help to define this 
> term.
>
> Djun Kim wrote:
>> I really don't want to reopen this debate.
>>
>> We have gone through this discussion already, and have added this
>> guideline to the style guide.    The page you are referring to merely
>> explains or amplifies some of the reasons we decided to STRONGLY
>> discourage embedded headers.
>>
>> I have spent tens of hours editing the handbook.  I've seen *hundreds*
>> of
>> examples of abused embedded headers, and only a handful of
>> examples where there wasn't clearly a better approach.
>>
>> This is a GUIDELINE, not a hard and fast rule.  Let's apply the
>> 80/20 rule - let anything that happens in fewer than 20% of the cases
>> be an EXCEPTION, and deal with it as such.  I  would say that
>> we're actually looking at fewer than 5% of cases.
>>
>> Re: Morkes and Nielsen.  I couldn't agree more with their
>> conclusions.  However, they would benefit from applying their
>> own findings.
>>
>> FIRST make the page concise.   Get rid of those ridiculous
>> pages that scroll on for screen after screen.  How? By breaking
>> them up along the lines of their embedded sections.
>>
>> The shorter pages are immediately more scannable.
>>
>>      Djun
>>
>>
>> On 3 Jun 2005, at 7:11 AM, Charlie Lowe wrote:
>>
>>
>>> I'd like us to address the usability of forbidding all heading 
>>> elements
>>> in handbook pages per these authoring guidelines:
>>>
>>> http://drupal.org/node/24221
>>>
>>> I don't disagree that longer pages which have multiple sections 
>>> should
>>> not be broken up into multiple pages, and I understand this is
>>> desirable
>>> so that Drupal can automatically generate headings for 
>>> printer-friendly
>>> output and other export of multiple handbook pages. But it's a common
>>> practice in web writing to use subheadings to make a single page more
>>> scannable. It is not always advantageous to the reader to break a 
>>> text
>>> with multiple small subsections into multiple pages where the reader
>>> has
>>> to follow multiple links just to see if the text in each is 
>>> applicable.
>>> Scanning one page can be much easier in certain instances; the
>>> alternative can also be too click-heavy. Sometimes, we don't want to
>>> push readers to follow links.
>>>
>>> Granted, as suggested, definition lists might work in certain 
>>> instances
>>> (however, I think the styling might require more padding for DT
>>> elements). But I'm not convinced it will work for all. For example, 
>>> see
>>>
>>> John Morkes and Jakob Nielsen's "Concise, SCANNABLE, and Objective:
>>> How to Write for the Web"
>>>
>>> http://www.useit.com/papers/webwriting/writing.html
>>>
>>> This article could definitely be broken up into multiple sections on
>>> multiple pages. But if you look at the "Findings" section, IMHO, the
>>> text would be more effective with the subsections for "Findings"
>>> included on the "Findings" page, and DT/DL elements don't seem the
>>> proper way to style it.
>>>
>>> Any thoughts on this?
>>>
>>> Charlie
>>> -- 
>>> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>>>
>>
>> --
>> Djun M. Kim, Director
>> djun.kim at cielosystems.com
>> Cielo Systems Inc.
>> http://www.cielosystems.com
>> Strategic Software Research                     Tel:   (604) 739-3941
>> 302 - 1298 10th Avenue West                     FAX:   (604) 739-3943
>> Vancouver, BC, V6H 1J4                          Mobile:(778) 895-1379
>>
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>
--
Djun M. Kim, Director                           
djun.kim at cielosystems.com
Cielo Systems Inc.                              
http://www.cielosystems.com
Strategic Software Research                     Tel:   (604) 739-3941
302 - 1298 10th Avenue West                     FAX:   (604) 739-3943
Vancouver, BC, V6H 1J4                          Mobile:(778) 895-1379