Reviewing the use of admonitions

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(a)redhat.com <mailto:daobrien@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(a)redhat.com <mailto:jfearn@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(a)redhat.com <mailto:daobrien@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(a)redhat.com <mailto:kwade@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(a)redhat.com <mailto:jfearn@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.