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 <[email protected]> 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 <[email protected]> > http://hibernate.org > > _______________________________________________ hibernate-dev mailing list [email protected] https://lists.jboss.org/mailman/listinfo/hibernate-dev
