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

[Steve Ebersole]

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