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

[Paul Benedict]

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