Note: This is a beta release of Red Hat Bugzilla 5.0. The data contained within is a snapshot of the live data so any changes you make will not be reflected in the production Bugzilla. Also email is disabled so feel free to test any aspect of the site that you want. File any problems you find or give feedback here.
Bug 456026 - Document Conventions needs urgent update
Summary: Document Conventions needs urgent update
Alias: None
Product: Publican
Classification: Community
Component: publican
Version: 2.0
Hardware: All
OS: Linux
Target Milestone: ---
Assignee: Brian Forte
QA Contact: Michael Hideo
Depends On:
TreeView+ depends on / blocked
Reported: 2008-07-20 23:42 UTC by Jeff Fearn 🐞
Modified: 2014-06-18 07:49 UTC (History)
3 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Last Closed: 2008-09-09 02:31:37 UTC

Attachments (Terms of Use)

Description Jeff Fearn 🐞 2008-07-20 23:42:39 UTC
Description of problem:

The Documentation Conventions uses visual style to explain the visual style.
This makes it impossible to know if the visual style is correct!

The Documentation Conventions should include a descriptive text that can be used
to verify the visual style is correct.

Comment 1 David O'Brien 2008-07-21 00:43:52 UTC
You beat me to it. This has needed updating for a while but I haven't gotten
around to it. Perhaps now would be a good time to get rid of the extra white
space in the examples, improve the content of the examples, and reduce the
number of admonitions (3 is plenty).

Comment 2 Jeff Fearn 🐞 2008-07-21 03:29:30 UTC
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 David O'Brien 2008-07-21 04:04:07 UTC
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 Karsten Wade 2008-07-21 07:14:16 UTC
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.

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

Comment 5 Jeff Fearn 🐞 2008-07-22 00:36:45 UTC
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.

Comment 6 Brian Forte 2008-09-09 02:31:37 UTC
A new Conventions.xml is now part of Publican 0.36.

The Notes and Warnings have been simplified (there were five, there are now three) as have the inline and block-level conventions for tags such as:

Note You need to log in before you can comment on or make changes to this bug.