Khronos Public Bugzilla
Bug 154 - "About This Manual" section needs some work
"About This Manual" section needs some work
Status: NEW
Product: COLLADA
Classification: Unclassified
Component: Specification
1.5.0
Macintosh Mac OS
: P3 normal
: Release 1.5.1
Assigned To: Fabrice Robinet
COLLADA Work Group email alias
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2009-04-22 17:10 PDT by Ellen Finch
Modified: 2014-01-07 10:30 PST (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Ellen Finch 2009-04-22 17:10:17 PDT
. Titled "about this manual" but almost everywhere else the spec is referred to as "document". Change all to "document".

2. Headers in About are formatted differently from everywhere else in the doc. Fix.

3. 3rd paragraph says "This document covers the initial design and specifications of the COLLADA schema, as well as a minimal set of requirements for COLLADA exporters. A short example of a COLLADA instance document is presented in “Appendix A”." This is an outdated description.

4. Audience section first paragraph has a couple of awkward commas.

5. Audience section says reader should "Have knowledge of XML and XML Schema." Better description is "Understand basic concepts of XML and of W3C XML schemas."  

5.a. QUESTION: For style guide, do we prefer "schemas" or "schemata" for plurals?

6. First sentence in "ntation/Organization" could be clearer. Current: 
"The schema reference chapters describe each feature  of the COLLADA schema syntax. Each XML element in the schema has the following sections:"
  Change to:
"The schema reference chapters describe each feature (XML element or major type) of the COLLADA schema syntax. Most XML elements and major types in the schema have reference entries similar to the following:"

6a. Then insert actual picture of typical page with callouts; this will make it easier to talk more clearly about the value of (and idiosyncrasies of) each part. 

7. Add index entry for "child order of elements" to reference the XML info, like "XML:order of child elements".

8. Other sources of information first 2 bullets are duplicated from the "audience" section"; delete.

9. Collada book typography:  COLLADA shd be all uppercase, 3D uppercase, Remi needs acute accent over e, space between AK.

10. All sources are given by name and are linked to URLs, but the URLs aren't visible in a printed version; we should  include the text of the URLs.