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(a)redhat.com <mailto:[e-mail]>) 	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:[e-mail]>) 	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:[e-mail]>) 	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:[e-mail]>) 	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:[e-mail]>) 	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.

[Paul W. Frields]

On Tue, 2008-07-22 at 12:07 +1000, David O'Brien wrote:
>  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: 
[...snip...]

>  Comment #4
> <https://bugzilla.redhat.com/show_bug.cgi?id=456026#c4> From 
>  Karsten Wade (kwade(a)redhat.com <mailto:[e-mail]>) 	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 
I think the GNOME methodology makes the most sense.  A tip offers
helpful but possibly unsolicited advice.  The info and note admonitions
are far closer in meaning, and could easily be combined.  Same goes for
caution and warning; the warning is simply a caution on steroids, so to
speak.

FWIW, I vote we go the GDP way.

-- 
Paul W. Frields
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://paul.frields.org/   -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Eric Christensen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I agree with the info and note being close.  I do think that the caution
and warning could be defined differently.  IF I were defining them I say
that CAUTION meant that you can do this but shouldn't unless you have
experience and WARNING means don't do this because you are getting ready
to fry your system.  I wouldn't want to dilute the WARNING down as I
want users to really pay attention to what is being said there and not
just pass it by only to delete everything on their system inadvertently.

Just my 2 cents worth.

Eric



Paul W. Frields wrote:
| On Tue, 2008-07-22 at 12:07 +1000, David O'Brien wrote:
|> http://library.gnome.org/devel/gdp-style-guide/2.22/infodesign-18.html.en
|
| I think the GNOME methodology makes the most sense.  A tip offers
| helpful but possibly unsolicited advice.  The info and note admonitions
| are far closer in meaning, and could easily be combined.  Same goes for
| caution and warning; the warning is simply a caution on steroids, so to
| speak.
|
| FWIW, I vote we go the GDP way.

> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
> Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org
>
> iEYEARECAAYFAkiHrh8ACgkQL5V8yddJCO1llQCeJOuiCdtsMVTqblUXn65pFT4y
> 2PUAnAxlLtFz6DOFGVZ51iknHRamTfbd
> =fF3q
> -----END PGP SIGNATURE-----

[Paul W. Frields]

On Wed, 2008-07-23 at 18:18 -0400, Eric Christensen wrote:
>  I agree with the info and note being close.  I do think that the
> caution
>  and warning could be defined differently.  IF I were defining them I say
>  that CAUTION meant that you can do this but shouldn't unless you have
>  experience and WARNING means don't do this because you are getting ready
>  to fry your system.  I wouldn't want to dilute the WARNING down as I
>  want users to really pay attention to what is being said there and not
>  just pass it by only to delete everything on their system inadvertently.
>  
>  Just my 2 cents worth. 
To which I would say, no one is worse off if the CAUTION becomes a
WARNING, as opposed to the opposite.  People should, given your logic --
with which I agree -- then be a little or a lot more careful than
otherwise, making the admonition that much more effective.  I wouldn't
want to dilute the WARNING; given a choice I'd prefer it.

-- 
Paul W. Frields
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://paul.frields.org/   -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Paul W. Frields]

On Wed, 2008-07-23 at 18:34 -0400, Paul W. Frields wrote:
>  On Wed, 2008-07-23 at 18:18 -0400, Eric Christensen wrote:
>  > I agree with the info and note being close.  I do think that the caution
>  > and warning could be defined differently.  IF I were defining them I say
>  > that CAUTION meant that you can do this but shouldn't unless you have
>  > experience and WARNING means don't do this because you are getting ready
>  > to fry your system.  I wouldn't want to dilute the WARNING down as I
>  > want users to really pay attention to what is being said there and not
>  > just pass it by only to delete everything on their system inadvertently.
>  > 
>  > Just my 2 cents worth.
>  
>  To which I would say, no one is worse off if the CAUTION becomes a
>  WARNING, as opposed to the opposite.  People should, given your logic --
>  with which I agree -- then be a little or a lot more careful than
>  otherwise, making the admonition that much more effective.  I wouldn't
>  want to dilute the WARNING; given a choice I'd prefer it. 
I apologize, this is in a little conflict with the GDP guidelines.  But
you should note that they have redefined CAUTION to mean what WARNING
would have meant before, and exactly what you describe -- making this
discussion purely semantics. :-)

-- 
Paul W. Frields
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://paul.frields.org/   -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Eric Christensen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Okay, so lets make it happen!

Eric



Paul W. Frields wrote:
| On Wed, 2008-07-23 at 18:34 -0400, Paul W. Frields wrote:
|> On Wed, 2008-07-23 at 18:18 -0400, Eric Christensen wrote:
|>> I agree with the info and note being close.  I do think that the caution
|>> and warning could be defined differently.  IF I were defining them I say
|>> that CAUTION meant that you can do this but shouldn't unless you have
|>> experience and WARNING means don't do this because you are getting ready
|>> to fry your system.  I wouldn't want to dilute the WARNING down as I
|>> want users to really pay attention to what is being said there and not
|>> just pass it by only to delete everything on their system inadvertently.
|>>
|>> Just my 2 cents worth.
|> To which I would say, no one is worse off if the CAUTION becomes a
|> WARNING, as opposed to the opposite.  People should, given your logic --
|> with which I agree -- then be a little or a lot more careful than
|> otherwise, making the admonition that much more effective.  I wouldn't
|> want to dilute the WARNING; given a choice I'd prefer it.
|
| I apologize, this is in a little conflict with the GDP guidelines.  But
| you should note that they have redefined CAUTION to mean what WARNING
| would have meant before, and exactly what you describe -- making this
| discussion purely semantics. :-)
|
|
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
> Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org
>
> iEYEARECAAYFAkiHuIgACgkQL5V8yddJCO1GgACfeZ+YIT9gSqCris8j/NsEHCq8
> JkkAn0dHD8NAPpUCqVf22UG4lu/qJjW4
> =AOHU
> -----END PGP SIGNATURE-----

[Paul W. Frields]

On Wed, 2008-07-23 at 19:02 -0400, Eric Christensen wrote:
>  -----BEGIN PGP SIGNED MESSAGE-----
>  Hash: SHA1
>  
>  Okay, so lets make it happen! 
Would you like to make the change to the Documentation Guide, advocating
the use of only tip, note, and caution with the definitions found at
GNOME?
http://library.gnome.org/devel/gdp-style-guide/2.22/infodesign-18.html.en

I can review the CVS commits you make before we republish.

Paul

http://www.idallen.com/topposting.html

[Karsten Wade]

On Wed, 2008-07-23 at 19:35 -0400, Paul W. Frields wrote:
>  On Wed, 2008-07-23 at 19:02 -0400, Eric Christensen wrote:
>  > -----BEGIN PGP SIGNED MESSAGE-----
>  > Hash: SHA1
>  > 
>  > Okay, so lets make it happen!
>  
>  Would you like to make the change to the Documentation Guide, advocating
>  the use of only tip, note, and caution with the definitions found at
>  GNOME?
>  http://library.gnome.org/devel/gdp-style-guide/2.22/infodesign-18.html.en 
David:

Thanks for getting this fixed 'upstream'. ;-)

Can you also chop and combine the parts in the wiki?

https://fedoraproject.org/wiki/Help:Editing#Notes.2C_Tips.2C_and_Other_Ad...

Maybe Nigel can run the wikibot to do the same combining in any pages
that use the admonitions?

- Karsten
-- 
Karsten Wade, Sr. Developer Community Mgr.
Dev Fu : http://developer.redhatmagazine.com
Fedora : http://quaid.fedorapeople.org
gpg key : AD0E0C41

[David O'Brien]

Karsten 'quaid' Wade wrote:
>  On Wed, 2008-07-23 at 19:35 -0400, Paul W. Frields wrote:
>    
> > On Wed, 2008-07-23 at 19:02 -0400, Eric Christensen wrote:
> >     
> >> -----BEGIN PGP SIGNED MESSAGE-----
> >> Hash: SHA1
> >>
> >> Okay, so lets make it happen!
> >>       
> > Would you like to make the change to the Documentation Guide, advocating
> > the use of only tip, note, and caution with the definitions found at
> > GNOME?
> > http://library.gnome.org/devel/gdp-style-guide/2.22/infodesign-18.html.en
> >     
>
>  David:
>
>  Thanks for getting this fixed 'upstream'. ;-)
>
>  Can you also chop and combine the parts in the wiki?
>
>  https://fedoraproject.org/wiki/Help:Editing#Notes.2C_Tips.2C_and_Other_Ad...
>
>  Maybe Nigel can run the wikibot to do the same combining in any pages
>  that use the admonitions?
>
>  - Karsten
>     
Brian & Jeff,
You two guys were having a side discussion on this topic. Where did you 
get to?

-- 

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.