Reviewing the use of admonitions

[David O'Brien]

The use of admonitions - their scope and definition - was raised as part 
of a style bug (Bugzilla 456026) and has developed a life of its own. 
Keeping Fedora and Red Hat doc policies in sync is generally considered 
A Good Thing, so I'm posting (almost) the complete list of comments here 
for further discussion:

Comment #1 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c1> From 
David O'Brien (daobrien at redhat.com <mailto:daobrien at redhat.com>) 	on 
2008-07-20 20:43 EST 	[reply 
<https://bugzilla.redhat.com/show_bug.cgi?id=456026#add_comment>] 	Private

Perhaps now would be a good time to <snip> reduce the
number of admonitions (3 is plenty).


Comment #2 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c2> From 
Jeff Fearn (jfearn at redhat.com <mailto:jfearn at redhat.com>) 	on 2008-07-20 
23:29 EST 	[reply 
<https://bugzilla.redhat.com/show_bug.cgi?id=456026#add_comment>] 	Private

I agree that 5 is over kill, however since we have a _lot_ of existing content
that uses all 5, it would be a major effort to remove the two we decide to drop.
Since this effort won't be undertaken it will mean we will ship books that use
admonitions not  discussed in the Documentation Conventions.

IMHO I think that three should be chose and from hereon the other 2 would not be
used and would, over time, be removed from existing docs. But until that process
is complete all 5 should remain documented in the conventions.


Comment #3 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c3> From 
David O'Brien (daobrien at redhat.com <mailto:daobrien at redhat.com>) 	on 
2008-07-21 00:04 EST 	[reply 
<https://bugzilla.redhat.com/show_bug.cgi?id=456026#add_comment>] 	Private

s/<caution>[whatever]</caution>/<warning>[whatever]</warning>/g ?  :-)

Yes, agreed, a bit of work involved in the update. Let's do Step 1 and decide on
the 2 to drop and the date for their cessation of use. How about:
- integrate Warning and Caution
- integrate Note and Tip
- decide if we still need Important

Probably a bit of redefinition will be required, and possibly a new bugzilla, as
I seem to have hijacked this one.


Comment #4 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c4> From 
Karsten Wade (kwade at redhat.com <mailto:kwade at redhat.com>) 	on 2008-07-21 
03:14 EST 	[reply 
<https://bugzilla.redhat.com/show_bug.cgi?id=456026#add_comment>] 	Private

Not to keep the hijacking up :), but here is something to add to your new bug
report regarding redefining admonitions.

There *are* differences between a note and a tip.  There is a difference between
offering warning and shouting caution.

https://fedoraproject.org/wiki/Help:Editing#Admonition_examples

Take it or leave it, but it is going to make it more difficult to integrate
documentation from/to Fedora if the policies are not in sync.  Thus, you might
want to take the discussion to fedora-docs-list.  You might find many receptive,
since the GNOME style guide is otherwise respected, and they agree with your
combination:

http://library.gnome.org/devel/gdp-style-guide/2.22/infodesign-18.html.en


Comment #5 <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c5> From 
Jeff Fearn (jfearn at redhat.com <mailto:jfearn at redhat.com>) 	on 2008-07-21 
20:36 EST 	[reply 
<https://bugzilla.redhat.com/show_bug.cgi?id=456026#add_comment>] 	Private

I agree with Karsten that it would be a damn fine idea for Red Hat and Fedora
docs to be in sync on this.

David could you either open a new bug or start a thread on the Fedora Docs list
about this.

Now let this bug continue on about clarifying the styles :)

Cheers, Jeff.


-- 

David O'Brien
IPA Content Author
Red Hat Asia Pacific

"We couldn't care less about comfort. We make you feel good."
Federico Minoli CEO Ducati Motor S.p.A.