[publican-list] RFC: Modified JBoss brand (was Re: RFE for Publican Brands)

[Joshua Wulf]

For adminitions I vote thin-rounded borders, no colours.

Right now the visual cueing in our docs doesn't help readers. They are
frequently presented with a page with multiple blocks of colours. These
are effectively flashing lights calling for their attention.

When you have a bank of controls and one flashing red light, your
attention is immediately directed there. When you have multiple flashing
lights of various colours, you just throw your hands up and go: "wtf?"

If there is one adminition in a book with a heavy-handed visual style,
it really calls attention to itself.

When there are multiple on a page the reader is fatigue, the effect is
overused and ineffective.

I think it's better that we rely on putting the reader into text
processing mode.

The icon is enough visual cueing - the border again allows them to
understand (and optionally to skip over) the scope of the adminition.

We should have a very clear and consistent guidelines on how we use the
adminitions, so that reader expectation of their information role can be
set and consistently reinforced.



On 10/13/2010 08:41 AM, misty at redhat.com wrote:
> 
> ----- "Jeffrey Fearn" <jfearn at redhat.com> wrote:
> 
>> Verbatim style: Like!
>>
>> Admonition Style: The borders aren't useful in differentiating the 
>> content. I think they could look better without them ... maybe new
>> icons 
>> would help there?
> 
> I think they need something besides the icons to differentiate them, especially the warning. At the same time, O'Reilly print documentation seems to use one icon for notice/tip/info and another one for warning/caution. No other differentiation. And they've sold a lot of books using this system. Any other thoughts on this? Maybe Sean has some thoughts (he is a usability expert after all).
> 
>>
>> Example Style: The colored border just looks wrong, this one has
>> always 
>> been the worst looking IMHO and the extra border was probably what was
>>
>> wrong with it. I think the title at the top is demarcation enough.
> 
> I think I agree with you and would like to change it to just a 1px dark grey border, with white text inside. Thoughts?
> 
>>
>> Figure Style: The title looks wrong at the top.
> 
> We all agree and I have changed it in my working copy.
> 
>>
>> We never tell people to manually copy files in to system areas, we
>> have 
>> processes to install them properly so their systems don't become hard
>> to 
>> upgrade, or recover[...]
> 
> Fair enough. In my enthusiasm I had forgotten that Publican has a procedure for installing brands.
> 
>>
>> You can put the zips on the publican wiki if you want, you just need
>> to 
>> login with your FAS details. The wiki is pretty open and anyone with a
>>
>> FAS account can edit it.
>>
>> Cheers, Jeff.
>>
>> -- 
>> Jeff Fearn <jfearn at redhat.com>
>> Software Engineer
>> Engineering Operations
>> Red Hat, Inc
>> Freedom ... courage ... Commitment ... ACCOUNTABILITY
>