Bug 456026
| Summary: | Document Conventions needs urgent update | ||
|---|---|---|---|
| Product: | [Community] Publican | Reporter: | Jeff Fearn 🐞 <jfearn> |
| Component: | publican | Assignee: | Brian Forte <bforte> |
| Status: | CLOSED CURRENTRELEASE | QA Contact: | Michael Hideo <mhideo> |
| Severity: | urgent | Docs Contact: | |
| Priority: | urgent | ||
| Version: | 2.0 | CC: | mmcallis, publican-list, rlandman |
| Target Milestone: | --- | Keywords: | Documentation |
| Target Release: | --- | ||
| Hardware: | All | ||
| OS: | Linux | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | Bug Fix | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2008-09-09 02:31:37 UTC | Type: | --- |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
| Embargoed: | |||
|
Description
Jeff Fearn 🐞
2008-07-20 23:42:39 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). 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. 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. 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 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. 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: <filename> <command> <keycap> <keycombo> <guimenu> <guilabel> <guibutton> <literal> <application> <replaceable> <computeroutput> <firstterm> <classname> |