All, It seems that the order of precedence is as confusing for everyone as it is for me =p. >From the discussion so far it would appear that Warning/Caution and Note/Tip/Important each mean roughly the same thing but have a slightly different strength of emphasis.
I think that it would be handy to come up with a useful definition for each of the admonitions this will help document writers and clearly help with designing or sourcing icons that try to convey each meaning. This definition can also be included in the Admonitions section of the QuickBook demo document to help writers. As Stjepan Rajko mentioned and John Maddock and Paul A Bristow re-iterated I also think it would be useful to generate a standard QuickBook document for Boost that provides the definitions and conventions used throughout any documentation (kind of like what is used within a hard copy text book to stipulate what different fonts, icons, callout boxes mean) this can help cut away any confusion potential readers or document writers would have. This could be stored centrally and then included during generation of any documentation. In my opinion it is worth stating up front that a possible option is to decide not to use a particular Admonition if its purpose is already served. I will see if I can gather our comments so far and paraphrase them succinctly to hopefully help us come up with something. But first I thought I would see what the Merriam-Webster dictionary (http://www.m-w.com) said on the matter. Tip (http://tinyurl.com/3dowrn) - "a : the usually pointed end of something <a pencil tip>" - "b : a small piece or part serving as an end, cap, or point" Note (http://tinyurl.com/348at4) - "a : to notice or observe with care" - "b : to record or preserve in writing" - "c : to make special mention of or remark on" Important (http://tinyurl.com/39g3ut) - "marked by or indicative of significant worth or consequence : valuable in content or relationship" Warn (http://tinyurl.com/yt9zfz) - "a : to give notice to beforehand especially of danger or evil" - "b : to give admonishing advice to" - "c : to call to one's attention" Caution (http://tinyurl.com/yogqtq) - "a : prudent forethought to minimize risk" - "b : one that astonishes or commands attention" - "c : to advise caution to warn" *Colours or lack of* I think that the agreement so far is the stronger Admonitions (Important, Warning and Caution) should be Yellow -> Orange -> Red (note the colour association still depends on the ultimate order of the admonitions). This seems to be a fairly safe convention. For Tip and Note the colours should be subtler (Blue, Green, Black?). As already mentioned on the wiki page and within this thread the icons should also recognisable in black and white form. *Shapes* For each icon if we can find or create them I think that Tip and Note should both be circles (with both colour and black and white versions) and then for the other three use a Triangle, Square and Hexagon *Order and Definition of each Admonition* There seems to be two preferences so far as to the order: 1. Important -> Warning -> Caution 2. Important -> Caution -> Warning Paul A Bristow proposed these definitions: Note - generally useful information (an aside that doesn't fit in the flow of the text). (blue i) Tip - suggestion on how to do something (especially something that not be obvious). (light bulb - lit!) Important - (note) on something to take particular notice of. (yellow triangle) Warning - take special care with this - it may not be what you expect and have bad results. (orange triangle) Caution - 'skull and crossbones' - this is likely to cause serious trouble if ignored. (red road sign triangle) Jake Voytko proposed this counterpoint: <--Jake's comments--> Personally, I think that "warning" is stronger than "caution", and would flip the signs that Paul proposed. To me, "caution" means that ignoring the admonition could lead to unexpected results. "Warning" means that failure to follow the admonition will not only lead to unexpected results, but that the results could also be harmful. The real world examples: "Caution, wet floor" is a common-place sign that is commonly ignored, but still offers good advice. Warning labels on products offer advice meant to spare life, limb, and health. <--End of Jake's comments--> *Conclusion* I think we all basically agree on the meanings of Tip, Note and Important. So at the end of the day unless someone can find a logical way to split the difference between Caution and Warning I think we should either flip a coin and stick with that decision or just go alphabetically ;) I hope this email has helped gather our thoughts. Peter. > -----Original Message----- > From: [EMAIL PROTECTED] [mailto:boost-docs- > [EMAIL PROTECTED] On Behalf Of Peter Foley > Sent: Wednesday, 18 July 2007 11:57 AM > To: [email protected] > Subject: [Boost-docs] Order of precedence for the Admonitions > > All, > > I have a question on what you feel the order of precedence is for the > Admonitions; specifically for Important, Caution and Warning. > > Do you feel that the order is Important --> Warning --> Caution (from > least strong to strongest). > > Also is it safe to say that if these icons were coloured Yellow --> > Orange --> Red. That this would help convey the strength of each > state? > > Thanks, > > Peter > > ----------------------------------------------------------------------- > -- > This SF.net email is sponsored by DB2 Express > Download DB2 Express C - the FREE version of DB2 express and take > control of your XML. No limits. Just data. Click to get it now. > http://sourceforge.net/powerbar/db2/ > _______________________________________________ > Boost-docs mailing list > [email protected] > Unsubscribe and other administrative requests: > https://lists.sourceforge.net/lists/listinfo/boost-docs ------------------------------------------------------------------------- This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
