| Summary: | Updates to Common Content required | ||
|---|---|---|---|
| Product: | [Community] Publican | Reporter: | Ruediger Landmann <rlandman> |
| Component: | publican | Assignee: | Ruediger Landmann <rlandman> |
| Status: | CLOSED CURRENTRELEASE | QA Contact: | tools-bugs <tools-bugs> |
| Severity: | medium | Docs Contact: | |
| Priority: | medium | ||
| Version: | future | CC: | aigao, daobrien, juwu, rlandman |
| Target Milestone: | --- | ||
| Target Release: | --- | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | 4.0.0 | Doc Type: | Bug Fix |
| Doc Text: | Story Points: | --- | |
| Clone Of: | 1027229 | Environment: | |
| Last Closed: | 2013-12-19 02:46:36 UTC | Type: | Bug |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
| Bug Depends On: | 1027229 | ||
| Bug Blocks: | |||
|
Description
Ruediger Landmann
2013-11-06 12:20:46 UTC
(In reply to Ruediger Landmann from comment #0) > +++ This bug was initially created as a clone of Bug #1027229 +++ Thanks for the review, David and Julie: > 1. Document Conventions > "Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts > set by default." > > Subject is plural and doesn't agree with verb. Already fixed in source for bug 952490 -- will be released with 4.0 > 1.1. Typographic Conventions > "Four typographic conventions are used to call attention to specific words > and phrases." > > Only three conventions are described. Four are described: * Mono-spaced bold * Proportional bold * Mono-spaced Bold Italic * Proportional Bold Italic even though the usage of the latter two is not differentiated. > "This denotes words or phrases encountered on a system, including > application names; dialog box text; labeled buttons; check-box and radio > button labels; menu titles and sub-menu titles." > > Treatment of compound adjectives is inconsistent. > s/sub-menu/submenu/ Will fix for 4.0 > "Note the words in bold italics above — username, domain.name, file-system, > package, version and release. Each word is a placeholder, either for text > you enter when issuing a command or for text displayed by the system." > > IBM recommends not using em dashes in tech pubs. I'll check their recommendation and get back on this (I don't have my copy of IBM with me), > 1.2. Pull-quote Conventions > "Output sent to a terminal is set in mono-spaced roman and presented thus:" > > Use of "thus" sounds... toffy. Maybe "as follows" or similar, as in the next > example? "Thus" is fine there; certainly not worth the translation overhead to change anyway. > 1.3. Notes and Warnings > Recommend changing heading to "Admonitions." "Admonitions" is the technical DocBook term for these structures, but I think it reduces clarity for people not thinking in DocBook. I suspect this would also be an interesting problem for translation, since most languages probably have a word meaning something close to "admonition" but probably zero have a word for the DocBook structure. > Also standardize text around > (e.g.), "<admonition_type> admonitions are..." See above for my thoughts on "admonitions". Moreover, I think that "Note admonitions are tips, shortcuts or alternative approaches" and "Warning admonitions should not be ignored" are considerably clunkier than what we have now and gain us nothing but conformity for its own sake. However, I'm certainly open to suggestions, but they would need to be really significant improvements on the existing text to justify the cost to translate. > "Ignoring a box labeled 'Important' will not cause data loss but may cause > irritation and frustration." > > Use double quotes for "Important." Will fix for 4.0 (In reply to Ruediger Landmann from comment #2) > (In reply to Ruediger Landmann from comment #0) > > +++ This bug was initially created as a clone of Bug #1027229 +++ > > Thanks for the review, David and Julie: > <snip> > > > 1.1. Typographic Conventions > > "Four typographic conventions are used to call attention to specific words > > and phrases." > > > > Only three conventions are described. > > Four are described: > > * Mono-spaced bold > * Proportional bold > * Mono-spaced Bold Italic > * Proportional Bold Italic > > even though the usage of the latter two is not differentiated. We did wonder about that. This "three vs four" comment came back from STC review of the book. > > > "This denotes words or phrases encountered on a system, including > > application names; dialog box text; labeled buttons; check-box and radio > > button labels; menu titles and sub-menu titles." > > > > Treatment of compound adjectives is inconsistent. > > s/sub-menu/submenu/ > > Will fix for 4.0 Great. > > > "Note the words in bold italics above — username, domain.name, file-system, > > package, version and release. Each word is a placeholder, either for text > > you enter when issuing a command or for text displayed by the system." > > > > IBM recommends not using em dashes in tech pubs. > > I'll check their recommendation and get back on this (I don't have my copy > of IBM with me), IBM p. 48: "Do not use en dashes or em dashes in technical information." > > > 1.2. Pull-quote Conventions > > "Output sent to a terminal is set in mono-spaced roman and presented thus:" > > > > Use of "thus" sounds... toffy. Maybe "as follows" or similar, as in the next > > example? > > "Thus" is fine there; certainly not worth the translation overhead to change > anyway. Good point. > > > 1.3. Notes and Warnings > > Recommend changing heading to "Admonitions." > > "Admonitions" is the technical DocBook term for these structures, but I > think it reduces clarity for people not thinking in DocBook. I suspect this > would also be an interesting problem for translation, since most languages > probably have a word meaning something close to "admonition" but probably > zero have a word for the DocBook structure. > > > Also standardize text around > > (e.g.), "<admonition_type> admonitions are..." > > See above for my thoughts on "admonitions". Moreover, I think that > > "Note admonitions are tips, shortcuts or alternative approaches" > > and > > "Warning admonitions should not be ignored" > > are considerably clunkier than what we have now and gain us nothing but > conformity for its own sake. > > However, I'm certainly open to suggestions, but they would need to be really > significant improvements on the existing text to justify the cost to > translate. Yes, can wear that. > > > "Ignoring a box labeled 'Important' will not cause data loss but may cause > > irritation and frustration." > > > > Use double quotes for "Important." > > Will fix for 4.0 Thanks. Not sure if there's much else that we would really like to get in, especially given that some are already fixed upstream. 6dfa968..007f85f devel -> devel |