[hibernate-dev] HHH 3.6 beta-2 docs: numbered steps

[Steve Ebersole]

Sure lets track them relative to both
http://opensource.atlassian.com/projects/hibernate/browse/HHH-5441
http://opensource.atlassian.com/projects/hibernate/browse/HHH-5466

To be honest I am not even sure with whom I need to follow up any more
in regards to the extra callout images.  I'd just as soon see if cutting
out the extraneous callout usage alleviates the need for them.  Trying
hard to imagine a scenario where reasonable (judicious) use of callouts
requires more than the 12 (i though it was 15) available images.  If we
find such a scenario I will follow up.

On Fri, 2010-08-06 at 11:43 -0500, Paul Benedict wrote:
> A couple thoughts on your response:
> 
> Let's create a JIRA issue to track this.
> 
> Second, please follow up on obtaining more images. I don't think every
> use of the "call out" is abusive, but I do think it is in several
> cases. When it comes to the HBM/XML attributes, I also believe it is
> overdone. My opinion is to reserve call outs for example code; the
> logic and reasoning behind examples require such pointers. .
> 
> Paul
> 
> On Fri, Aug 6, 2010 at 11:31 AM, Steve Ebersole <steve at hibernate.org>
> wrote:
>         On Fri, 2010-08-06 at 10:23 -0500, Paul Benedict wrote:
>         > I was browsing the latest docs. Congrats to everyone merging
>         the annotation
>         > documentation!
>         
>         
>         A few people had hands in that.  Hardy and Emmanuel did most
>         of it.
>         
>         >
>         > When it comes to the number/bulleted steps, I believe images
>         for beyond "12"
>         > do not exist; yet the largest step I saw was around 17. I
>         don't know how you
>         > guys get those images -- free from the web or from your
>         graphic artists or
>         > otherwise. This is just an FYI in case no one noticed you
>         need more
>         > (probably up to number 20). Resolving this would help polish
>         the
>         > documentation's look.
>         
>         
>         Totally agree.  For the record those are called callouts (you
>         are
>         calling out attention to something specific).  DocBook
>         provides for
>         callouts to be either graphical (images) or text (the '(1)'
>         style you
>         mention).  By default DocBook wants to use images, however it
>         only
>         supplies a limited number of icons.  I requested quite a long
>         time ago
>         that we get an expanded set of callout images from the Red Hat
>         design
>         team.  I can follow up with that.  So that is certainly one
>         option.
>         
>         Another option is to not use graphic callouts at all.
>         
>         Yet another thing to consider is that I have actually been
>         told that we
>         over use callouts.  Specifically we use them in ways they are
>         not
>         intended to be used.  Where we usually "run out of icons" is
>         in the
>         callouts used to document the various hbm.xml element
>         attributes.  I
>         have been told that calling out every single line in a
>         programlisting
>         like that is not the intended use of callouts and that
>         something like a
>         variable list (think a list of terms and their definition)
>         would better
>         suit that usage.  So that is a third option.
>         
>         --
>         Steve Ebersole <steve at hibernate.org>
>         http://hibernate.org
>         
> 

-- 
Steve Ebersole <steve at hibernate.org>
http://hibernate.org