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

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(a)hibernate.org&gt; 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(a)hibernate.org&gt; http://hibernate.org