[hibernate-dev] HHH 3.6 beta-2 docs: numbered steps
pbenedict at apache.org
Fri Aug 6 12:43:25 EDT 2010
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. .
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
> > 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
> > do not exist; yet the largest step I saw was around 17. I don't know how
> > guys get those images -- free from the web or from your graphic artists
> > 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>
More information about the hibernate-dev