19 lines
3.2 KiB
Plaintext
19 lines
3.2 KiB
Plaintext
|
%META:TOPICINFO{author="GregorHagedorn" date="1139242326" format="1.1" version="1.2"}%
|
||
|
|
%META:TOPICPARENT{name="TipDocumentsInitialStandardsPage"}%
|
||
|
|
---+ Feedback on Files Admin Standard
|
||
|
|
(back to TipDocumentsInitialStandardsPage)
|
||
|
|
|
||
|
|
---+++Gregor Hagedorn:
|
||
|
|
|
||
|
|
* Point "2 Contents of Standards": I believe the file naming conventions currently applied need to be reconsidered. These are partly mentioned under this point. Reading the entire "Initial Administrative Standards" pages initially confused me a lot and I realized only after more than an hour that this was largely due to the current file naming conventions.
|
||
|
|
* The first problem I see is that the extension xml is used for both documents addressing humans and documents addressing machines. My major initial mistake was that I opened the cover.xml to learn about the standard and assumed that standard.xml is a technical documentation (schema or other). I know realize that the reverse is the case and delete a lot of comments from my email...
|
||
|
|
* However, perhaps the term "cover page" should be exchanged. It is well known and a very useful website (xml.coverpages.org) establishes some idea in my head what a cover page is. Talking of a page I think of an html or wiki page. The data seem to be about technically expressed metadata for a standard, not a readable cover page. Renaming it to metadata.xml would help me. If we want to keep "cover", perhaps "cover.rdf.xml" or something making it clear that humans should not attempt to read this.
|
||
|
|
* To me it would also be helpful to not call html pages addressing humans ".xml", but rather xthml or no extension at all. Clearly this is arbitrary, but my immediate experience shows that in the absence of other hints on human readability, a file called standard.xml was by me considered to contain program data, not text.
|
||
|
|
* Point "5 Versioning": "This date is recorded in the file name for the standard and in the Cover Page document." -- The example do not follow this and can not because not released. Some additional thought needs to be made how pre-release documents are to be versioned and distinguished.
|
||
|
|
* With regard to this point: I would welcome if for the next round of revision the documents would be directly in the Wiki, so comments can be read in place. This would take care of versioning during development. The previous round of documents seemed to use Word seems to use non-Wiki xhtml even for human readable documents. The separation of content and discussion made it rather difficult for me to follow the discussions. Copying the document into the Wiki (or developing it inside) would allow for in-place discussions.
|
||
|
|
* If developed inside the wiki, archival copies could be created using a twiki wiki to xhtml conversion tool (Bob Morris installed one on his TWiki; I am not sure whether separate installation is necessary).
|
||
|
|
* Point "6 File Formats" explains that several file formats are acceptable, but does not specify for which part of a standard. In /standards/tdwg_admin_cover_page/standard.xml this is contradicted by saying:
|
||
|
|
"The Cover Page file must be a well formed XML document following the RDF/XML syntax specification (http://www.w3.org/TR/rdf-syntax-grammar/)and have an encoding of UTF-8."
|
||
|
|
|
||
|
|
-- Main.GregorHagedorn - 06 Feb 2006
|