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

[Sean Rogers]

----- 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).

I agree they need more than just an icon for accessibility. Since the title is configurable, and generally should not just say "Note", it can't be relied on. Colour is usually not a good way to differentiate things by itself, but in combination with the icon it is OK. I think admonitions need a border to separate them from any following text. This is why sections can't have following paras: without a border admonitions would essentially just become sections and following paras would not look right.

| 
| > 
| > 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?

I admit I do like the look of the example without a border, but for the same reasons as above I think we need a border, even more so since they're typically longer than admonitions. Originally I thought that borderless could work since it works for procedures, but procedures are typically part of the flow of the content while examples often act as asides. 1px could possibly work but I feel a thicker one designates that as more of a separate block. Examples should be able to be skipped when reading, and a thicker border facilitates this easier than a thicker one for me.

| 
| > 
| > 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
| 
| -- 
| Misty Stanley-Jones
| Content Author, ECS Brisbane
| Ph: +61 7 3514 8105
| RHCT #60501081553354
| Purgamentum init, exit purgamentum.
| 
| _______________________________________________
| publican-list mailing list
| publican-list at redhat.com
| https://www.redhat.com/mailman/listinfo/publican-list
| Wiki: https://fedorahosted.org/publican