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

[Sean Rogers]

I don't think anyone is arguing in favour of the colour blocks we currently have. Yet your argument is mostly why I wanted a grey border for notes instead of the green they previously were: green made them stand out and flash, which is not really what notes are meant for. Warnings and Importants do need to stand out though, as it is usually essential for the reader to read them.

We do have clear guidelines for the use of admonitions, it's what is listed in the Preface material. Overuse should be avoided for the reasons you state.

I should also clarify my previous comment about not being able to use the titles for admonition differentiation: Ryan has reminded me that a while back when the admonition title discussion was had, the consensus was that titles should be specified, but they should include the type of admonition; for example: "Important: Don't forget to wear pants". In this case the title can be relied on. The more I think about it the colours aren't really necessary for admonitions, it just looks weird with them being all the same colour when they're next to each other, which they typically should not be in normal use.

- Sean

----- "Joshua Wulf" <jwulf at redhat.com> wrote:

| 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
| > 
| 
| _______________________________________________
| publican-list mailing list
| publican-list at redhat.com
| https://www.redhat.com/mailman/listinfo/publican-list
| Wiki: https://fedorahosted.org/publican