So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision. One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted. During the F2F, I raised the issue that it may be worthwhile to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents. This aids in help keeping track of what document is "best current practice", as well as making it clear what has changed from version to version. For example, when UASG 5/7 is revised, we publish them under new numbers, and the old versions are archived with a clear note that they've been obsoleted by these new versions of the doucments. This would make it easy to keep up with current best practices, while making it easy to look at a document when referencing old conversations and changes over time. Anyone have thoughts on making this change? Michael
UA Colleagues: I think the problem Michael points out is a real one, and worthy of attention. On 2019-01-08 07:03, Michael Casadevall wrote:
So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision.
One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted.... Michael proposes one alternative, …to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.…
Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview". Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite. I believe we should also define standard, persistent URLs for each document, something like: http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time. Best regard, —Jim DeLaHunt, Vancouver, Canada -- --Jim DeLaHunt, jdlh@jdlh.com http://blog.jdlh.com/ (http://jdlh.com/) multilingual websites consultant 355-1027 Davie St, Vancouver BC V6E 4L2, Canada Canada mobile +1-604-376-8953
For comparison, the Unicode Standard has the model where a link generally would get you the latest version of a document, but each document contains a header with a link to the previous revision of the document. That way, if you want to point people to the latest version of a document you can use an "evergreen" link, but if you need to be sure that the link goes to a specific version, there's that option as well. http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... or http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would get the latest version and http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would be a specific version. Each version remaining unaltered once posted. A./ On 1/8/2019 12:54 PM, Jim DeLaHunt wrote:
UA Colleagues:
I think the problem Michael points out is a real one, and worthy of attention.
On 2019-01-08 07:03, Michael Casadevall wrote:
So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision.
One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted.... Michael proposes one alternative, …to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.…
Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview".
Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite.
I believe we should also define standard, persistent URLs for each document, something like:
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time.
Best regard, —Jim DeLaHunt, Vancouver, Canada
Asmus/Jim, That sounds like a model with a basic name (Unicode) with a version number. Different from the IETF model. As to persistent URLs, yes a problem to be resolved, regardless of which numbering model to adopt. -Ram *From:* Asmus Freytag <asmusf@ix.netcom.com> *Sent:* Tuesday, January 8, 2019 4:31 PM *To:* ua-discuss@icann.org *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents For comparison, the Unicode Standard has the model where a link generally would get you the latest version of a document, but each document contains a header with a link to the previous revision of the document. That way, if you want to point people to the latest version of a document you can use an "evergreen" link, but if you need to be sure that the link goes to a specific version, there's that option as well. http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... or http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would get the latest version and http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would be a specific version. Each version remaining unaltered once posted. A./ On 1/8/2019 12:54 PM, Jim DeLaHunt wrote: UA Colleagues: I think the problem Michael points out is a real one, and worthy of attention. On 2019-01-08 07:03, Michael Casadevall wrote: So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision. One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted.... Michael proposes one alternative, …to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.… Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview". Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite. I believe we should also define standard, persistent URLs for each document, something like: http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time. Best regard, —Jim DeLaHunt, Vancouver, Canada
On 1/8/2019 3:58 PM, Mike Hemp wrote:
For the god sake do not make it complicated for people. RFC/IETF is only for highly technical community not for website and general application developers. Keep complications behind and keep the things simple for general audience. UASG is for everyone and must be understood very easily. Asmus idea is great. Get rid of numbers please. People who make money from technical stuff make issues complicated and would come up with such ideas.
W3C manages without numbers. But that requires short names like "CSS" or "HTML" or something. Having to always cite documents by a full title like "email address internationalization EAI a technical_overview" gets pretty old. However, changing the title around a bit to something like EAI Overview: Email Address Internationalization (EAI), would allow "EAI Oveview" or "UASG EAI Overview" as shorthand, which arguably would be more self-explanatory than UASG 02. A./
*Sent:* Wednesday, January 09, 2019 at 3:01 AM *From:* "Asmus Freytag" <asmusf@ix.netcom.com> *To:* ua-discuss@icann.org *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents For comparison, the Unicode Standard has the model where a link generally would get you the latest version of a document, but each document contains a header with a link to the previous revision of the document. That way, if you want to point people to the latest version of a document you can use an "evergreen" link, but if you need to be sure that the link goes to a specific version, there's that option as well. http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... or http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would get the latest version and http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would be a specific version. Each version remaining unaltered once posted. A./ On 1/8/2019 12:54 PM, Jim DeLaHunt wrote:
UA Colleagues:
I think the problem Michael points out is a real one, and worthy of attention.
On 2019-01-08 07:03, Michael Casadevall wrote:
So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision.
One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted....
Michael proposes one alternative,
…to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.…
Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview".
Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite.
I believe we should also define standard, persistent URLs for each document, something like:
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time.
Best regard, —Jim DeLaHunt, Vancouver, Canada
Thanks for comments. Here’s my proposal Document Naming and Storage Conventions From time to time the UASG will review and revise documents. The UASG’s naming and storage policy for the documents will be: * Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document * Document Revision – (e.g. UASG000 – 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. * Document Link – (e.g. English https://uasg.tech/wp-content/uploads/UASG-000-Inventory-of-Material.pdf ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. * Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) * Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done. From: UA-discuss <ua-discuss-bounces@icann.org> On Behalf Of Asmus Freytag (c) Sent: Wednesday, 9 January 2019 2:09 PM To: Mike Hemp <mikehamp1971@mail.com> Cc: ua-discuss@icann.org Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents On 1/8/2019 3:58 PM, Mike Hemp wrote: For the god sake do not make it complicated for people. RFC/IETF is only for highly technical community not for website and general application developers. Keep complications behind and keep the things simple for general audience. UASG is for everyone and must be understood very easily. Asmus idea is great. Get rid of numbers please. People who make money from technical stuff make issues complicated and would come up with such ideas. W3C manages without numbers. But that requires short names like "CSS" or "HTML" or something. Having to always cite documents by a full title like "email address internationalization EAI a technical_overview" gets pretty old. However, changing the title around a bit to something like EAI Overview: Email Address Internationalization (EAI), would allow "EAI Oveview" or "UASG EAI Overview" as shorthand, which arguably would be more self-explanatory than UASG 02. A./ Sent: Wednesday, January 09, 2019 at 3:01 AM From: "Asmus Freytag" <asmusf@ix.netcom.com><mailto:asmusf@ix.netcom.com> To: ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents For comparison, the Unicode Standard has the model where a link generally would get you the latest version of a document, but each document contains a header with a link to the previous revision of the document. That way, if you want to point people to the latest version of a document you can use an "evergreen" link, but if you need to be sure that the link goes to a specific version, there's that option as well. http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... or http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would get the latest version and http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would be a specific version. Each version remaining unaltered once posted. A./ On 1/8/2019 12:54 PM, Jim DeLaHunt wrote: UA Colleagues: I think the problem Michael points out is a real one, and worthy of attention. On 2019-01-08 07:03, Michael Casadevall wrote: So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision. One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted.... Michael proposes one alternative, …to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.… Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview". Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite. I believe we should also define standard, persistent URLs for each document, something like: http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time. Best regard, —Jim DeLaHunt, Vancouver, Canada
UASG Colleagues: [keeping list address, dropping redundant individual addresses] I'm glad to see this discussion moving towards a convention which addresses some of the issues raised. Some comments on Don's proposal interleaved below. On 2019-01-24 08:23, Don Hollander wrote:
Thanks for comments. Here’s my proposal
Document Naming and Storage Conventions
From time to time the UASG will review and revise documents. The UASG’s naming and storage policy for the documents will be:
* Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document
This proposal seems to adopt a number and reject Asmus' proposal for a short title phrase as the consistent reference name. I see the value of having a document number, but I think having a consistent short title phrase is also valuable.
* Document Revision – (e.g. UASG000 – 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document.
I like using a date in yyyy-mm-dd format as a document revision code.
* Document Link – (e.g. English https://uasg.tech/wp-content/uploads/UASG-000-Inventory-of-Material.pdf ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document.
I have reservations about embedding text like "wp-content/uploads/" in the official document link for our documents. It seems to be an artifact of our current website technology, which has no place in the official link. I would suggest a link authored solely for being a clear reference, e.g. https://uasg.tech/publications/UASG000-Inventory-of-Material/ If we are using document numbers, we should use them consistency. Note "UASG-000" in the proposed document link differs from "UASG000", the proposed document number. They should be the same. It might be good to insert a language code in our URLs. I hope in good time we will have our website and our important publications in several different languages. The document link might be, https://uasg.tech/en/publications/UASG000-Inventory-of-Material/ The same document can be published in different formats. Additionally, there is a need to refer to metadata about the document. Metadata includes: a list of links to different revisions of the document, a list of links to different language versions of the same document, an abstract, revision details, and so on. So, I propose we make a Document Link structure which can consistently refer to: * the PDF representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.pdf, * the HTML representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.html, * the HTML representation of metadata revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material, * the (PDF or other format) representation of a specific revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material/2019-01-24/U..., * all of the above in a different language, e.g. https://uasg.tech/ja/文書/UASG000-文書一覧.pdf [Example only; I am not a skilled speaker of Japanese, I probably made bad choices for the translation into Japanese. —Jim]
* Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date)
Agreed. I am proposing that one link to the deprecated version of documents be in the metadata page for that document, and that our document link convention specify the document link format for deprecated versions also.
* Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done.
Agreed. I am also proposing that the metadata page for a document include a summary of revisions, even for brochures. Other comments? —Jim DeLaHunt, Vancouver, Canada
*From:*UA-discuss <ua-discuss-bounces@icann.org> *On Behalf Of *Asmus Freytag (c) *Sent:* Wednesday, 9 January 2019 2:09 PM *To:* Mike Hemp <mikehamp1971@mail.com> *Cc:* ua-discuss@icann.org *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents
On 1/8/2019 3:58 PM, Mike Hemp wrote:
For the god sake do not make it complicated for people. RFC/IETF is only for highly technical community not for website and general application developers. Keep complications behind and keep the things simple for general audience. UASG is for everyone and must be understood very easily. Asmus idea is great. Get rid of numbers please. People who make money from technical stuff make issues complicated and would come up with such ideas.
W3C manages without numbers.
But that requires short names like "CSS" or "HTML" or something.
Having to always cite documents by a full title like "email address internationalization EAI a technical_overview" gets pretty old. However, changing the title around a bit to something like EAI Overview: Email Address Internationalization (EAI), would allow "EAI Oveview" or "UASG EAI Overview" as shorthand, which arguably would be more self-explanatory than UASG 02.
A./
*Sent:* Wednesday, January 09, 2019 at 3:01 AM *From:* "Asmus Freytag" <asmusf@ix.netcom.com> <mailto:asmusf@ix.netcom.com> *To:* ua-discuss@icann.org <mailto:ua-discuss@icann.org> *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents
For comparison, the Unicode Standard has the model where a link generally would get you the latest version of a document, but each document contains a header with a link to the previous revision of the document.
That way, if you want to point people to the latest version of a document you can use an "evergreen" link, but if you need to be sure that the link goes to a specific version, there's that option as well.
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
or
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
would get the latest version and
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
would be a specific version. Each version remaining unaltered once posted.
A./
On 1/8/2019 12:54 PM, Jim DeLaHunt wrote:
UA Colleagues:
I think the problem Michael points out is a real one, and worthy of attention.
On 2019-01-08 07:03, Michael Casadevall wrote:
So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision.
One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted....
Michael proposes one alternative,
…to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.…
Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview".
Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite.
I believe we should also define standard, persistent URLs for each document, something like:
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time.
Best regard, —Jim DeLaHunt, Vancouver, Canada
-- --Jim DeLaHunt, jdlh@jdlh.com http://blog.jdlh.com/ (http://jdlh.com/) multilingual websites consultant 355-1027 Davie St, Vancouver BC V6E 4L2, Canada Canada mobile +1-604-376-8953
Jim, I find your observations reasonable and don’t have any additional comments. That said, I would be cautious to not let perfection get in the way of good enough. That seems to apply here. My two cents. Dennis From: UA-discuss <ua-discuss-bounces@icann.org> on behalf of Jim DeLaHunt <list+uasg@jdlh.com> Date: Thursday, January 24, 2019 at 3:27 PM To: "UA-discuss@icann.org" <ua-discuss@icann.org> Subject: [EXTERNAL] Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents UASG Colleagues: [keeping list address, dropping redundant individual addresses] I'm glad to see this discussion moving towards a convention which addresses some of the issues raised. Some comments on Don's proposal interleaved below. On 2019-01-24 08:23, Don Hollander wrote: Thanks for comments. Here’s my proposal Document Naming and Storage Conventions From time to time the UASG will review and revise documents. The UASG’s naming and storage policy for the documents will be: · Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document This proposal seems to adopt a number and reject Asmus' proposal for a short title phrase as the consistent reference name. I see the value of having a document number, but I think having a consistent short title phrase is also valuable. · Document Revision – (e.g. UASG000 – 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. I like using a date in yyyy-mm-dd format as a document revision code. · Document Link – (e.g. English https://uasg.tech/wp-content/uploads/UASG-000-Inventory-of-Material.pdf ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. I have reservations about embedding text like "wp-content/uploads/" in the official document link for our documents. It seems to be an artifact of our current website technology, which has no place in the official link. I would suggest a link authored solely for being a clear reference, e.g. https://uasg.tech/publications/UASG000-Inventory-of-Material/ If we are using document numbers, we should use them consistency. Note "UASG-000" in the proposed document link differs from "UASG000", the proposed document number. They should be the same. It might be good to insert a language code in our URLs. I hope in good time we will have our website and our important publications in several different languages. The document link might be, https://uasg.tech/en/publications/UASG000-Inventory-of-Material/ The same document can be published in different formats. Additionally, there is a need to refer to metadata about the document. Metadata includes: a list of links to different revisions of the document, a list of links to different language versions of the same document, an abstract, revision details, and so on. So, I propose we make a Document Link structure which can consistently refer to: · the PDF representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.pdf, · the HTML representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.html, · the HTML representation of metadata revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material, · the (PDF or other format) representation of a specific revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material/2019-01-24/U..., · all of the above in a different language, e.g. https://uasg.tech/ja/文書/UASG000-文書一覧.pdf [Example only; I am not a skilled speaker of Japanese, I probably made bad choices for the translation into Japanese. —Jim] · Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) Agreed. I am proposing that one link to the deprecated version of documents be in the metadata page for that document, and that our document link convention specify the document link format for deprecated versions also. · Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done. Agreed. I am also proposing that the metadata page for a document include a summary of revisions, even for brochures. Other comments? —Jim DeLaHunt, Vancouver, Canada From: UA-discuss <ua-discuss-bounces@icann.org><mailto:ua-discuss-bounces@icann.org> On Behalf Of Asmus Freytag (c) Sent: Wednesday, 9 January 2019 2:09 PM To: Mike Hemp <mikehamp1971@mail.com><mailto:mikehamp1971@mail.com> Cc: ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents On 1/8/2019 3:58 PM, Mike Hemp wrote: For the god sake do not make it complicated for people. RFC/IETF is only for highly technical community not for website and general application developers. Keep complications behind and keep the things simple for general audience. UASG is for everyone and must be understood very easily. Asmus idea is great. Get rid of numbers please. People who make money from technical stuff make issues complicated and would come up with such ideas. W3C manages without numbers. But that requires short names like "CSS" or "HTML" or something. Having to always cite documents by a full title like "email address internationalization EAI a technical_overview" gets pretty old. However, changing the title around a bit to something like EAI Overview: Email Address Internationalization (EAI), would allow "EAI Oveview" or "UASG EAI Overview" as shorthand, which arguably would be more self-explanatory than UASG 02. A./ Sent: Wednesday, January 09, 2019 at 3:01 AM From: "Asmus Freytag" <asmusf@ix.netcom.com><mailto:asmusf@ix.netcom.com> To: ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents For comparison, the Unicode Standard has the model where a link generally would get you the latest version of a document, but each document contains a header with a link to the previous revision of the document. That way, if you want to point people to the latest version of a document you can use an "evergreen" link, but if you need to be sure that the link goes to a specific version, there's that option as well. http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... or http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would get the latest version and http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would be a specific version. Each version remaining unaltered once posted. A./ On 1/8/2019 12:54 PM, Jim DeLaHunt wrote: UA Colleagues: I think the problem Michael points out is a real one, and worthy of attention. On 2019-01-08 07:03, Michael Casadevall wrote: So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision. One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted.... Michael proposes one alternative, …to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.… Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview". Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite. I believe we should also define standard, persistent URLs for each document, something like: http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time. Best regard, —Jim DeLaHunt, Vancouver, Canada -- --Jim DeLaHunt, jdlh@jdlh.com<mailto:jdlh@jdlh.com> http://blog.jdlh.com/ (http://jdlh.com/) multilingual websites consultant 355-1027 Davie St, Vancouver BC V6E 4L2, Canada Canada mobile +1-604-376-8953
All, the virtue of a document number is that it makes it easier to correlate translations and give each document a translated name. That might outweigh the downside of having it so prominent in the first place. Jim's comment about consistent punctuation in document numbering is spot on. I also like to second his suggestion for structuring the path. A./ PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation. On 1/24/2019 12:26 PM, Jim DeLaHunt wrote:
UASG Colleagues: [keeping list address, dropping redundant individual addresses]
I'm glad to see this discussion moving towards a convention which addresses some of the issues raised. Some comments on Don's proposal interleaved below.
On 2019-01-24 08:23, Don Hollander wrote:
Thanks for comments. Here’s my proposal
Document Naming and Storage Conventions
From time to time the UASG will review and revise documents. The UASG’s naming and storage policy for the documents will be:
* Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document
This proposal seems to adopt a number and reject Asmus' proposal for a short title phrase as the consistent reference name. I see the value of having a document number, but I think having a consistent short title phrase is also valuable.
* Document Revision – (e.g. UASG000 – 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document.
I like using a date in yyyy-mm-dd format as a document revision code.
* Document Link – (e.g. English https://uasg.tech/wp-content/uploads/UASG-000-Inventory-of-Material.pdf ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document.
I have reservations about embedding text like "wp-content/uploads/" in the official document link for our documents. It seems to be an artifact of our current website technology, which has no place in the official link.
I would suggest a link authored solely for being a clear reference, e.g.
https://uasg.tech/publications/UASG000-Inventory-of-Material/
If we are using document numbers, we should use them consistency. Note "UASG-000" in the proposed document link differs from "UASG000", the proposed document number. They should be the same.
It might be good to insert a language code in our URLs. I hope in good time we will have our website and our important publications in several different languages. The document link might be,
https://uasg.tech/en/publications/UASG000-Inventory-of-Material/
The same document can be published in different formats. Additionally, there is a need to refer to metadata about the document. Metadata includes: a list of links to different revisions of the document, a list of links to different language versions of the same document, an abstract, revision details, and so on.
So, I propose we make a Document Link structure which can consistently refer to:
* the PDF representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.pdf, * the HTML representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.html, * the HTML representation of metadata revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material, * the (PDF or other format) representation of a specific revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material/2019-01-24/U...,
* all of the above in a different language, e.g. https://uasg.tech/ja/文書/UASG000-文書一覧.pdf [Example only; I am not a skilled speaker of Japanese, I probably made bad choices for the translation into Japanese. —Jim]
* Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date)
Agreed. I am proposing that one link to the deprecated version of documents be in the metadata page for that document, and that our document link convention specify the document link format for deprecated versions also.
* Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done.
Agreed. I am also proposing that the metadata page for a document include a summary of revisions, even for brochures.
Other comments? —Jim DeLaHunt, Vancouver, Canada
*From:*UA-discuss <ua-discuss-bounces@icann.org> *On Behalf Of *Asmus Freytag (c) *Sent:* Wednesday, 9 January 2019 2:09 PM *To:* Mike Hemp <mikehamp1971@mail.com> *Cc:* ua-discuss@icann.org *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents
On 1/8/2019 3:58 PM, Mike Hemp wrote:
For the god sake do not make it complicated for people. RFC/IETF is only for highly technical community not for website and general application developers. Keep complications behind and keep the things simple for general audience. UASG is for everyone and must be understood very easily. Asmus idea is great. Get rid of numbers please. People who make money from technical stuff make issues complicated and would come up with such ideas.
W3C manages without numbers.
But that requires short names like "CSS" or "HTML" or something.
Having to always cite documents by a full title like "email address internationalization EAI a technical_overview" gets pretty old. However, changing the title around a bit to something like EAI Overview: Email Address Internationalization (EAI), would allow "EAI Oveview" or "UASG EAI Overview" as shorthand, which arguably would be more self-explanatory than UASG 02.
A./
*Sent:* Wednesday, January 09, 2019 at 3:01 AM *From:* "Asmus Freytag" <asmusf@ix.netcom.com> <mailto:asmusf@ix.netcom.com> *To:* ua-discuss@icann.org <mailto:ua-discuss@icann.org> *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents
For comparison, the Unicode Standard has the model where a link generally would get you the latest version of a document, but each document contains a header with a link to the previous revision of the document.
That way, if you want to point people to the latest version of a document you can use an "evergreen" link, but if you need to be sure that the link goes to a specific version, there's that option as well.
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
or
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
would get the latest version and
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
would be a specific version. Each version remaining unaltered once posted.
A./
On 1/8/2019 12:54 PM, Jim DeLaHunt wrote:
UA Colleagues:
I think the problem Michael points out is a real one, and worthy of attention.
On 2019-01-08 07:03, Michael Casadevall wrote:
So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision.
One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted....
Michael proposes one alternative,
…to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.…
Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview".
Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite.
I believe we should also define standard, persistent URLs for each document, something like:
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time.
Best regard, —Jim DeLaHunt, Vancouver, Canada
-- --Jim DeLaHunt,jdlh@jdlh.com http://blog.jdlh.com/ (http://jdlh.com/) multilingual websites consultant
355-1027 Davie St, Vancouver BC V6E 4L2, Canada Canada mobile +1-604-376-8953
I think the suggestion from Don and refinements from Jim and Asmus are fine. I also agree with Dennis about striving for perfection; the fewer chefs in the kitchen, the better, so I defer to the team. --Rich Richard Merdinger VP, Domains rmerdinger@godaddy.com<mailto:rmerdinger@godaddy.com> From: UA-discuss <ua-discuss-bounces@icann.org> on behalf of Asmus Freytag <asmusf@ix.netcom.com> Date: Thursday, January 24, 2019 at 4:20 PM To: "ua-discuss@icann.org" <ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents All, the virtue of a document number is that it makes it easier to correlate translations and give each document a translated name. That might outweigh the downside of having it so prominent in the first place. Jim's comment about consistent punctuation in document numbering is spot on. I also like to second his suggestion for structuring the path. A./ PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation. On 1/24/2019 12:26 PM, Jim DeLaHunt wrote: UASG Colleagues: [keeping list address, dropping redundant individual addresses] I'm glad to see this discussion moving towards a convention which addresses some of the issues raised. Some comments on Don's proposal interleaved below. On 2019-01-24 08:23, Don Hollander wrote: Thanks for comments. Here’s my proposal Document Naming and Storage Conventions From time to time the UASG will review and revise documents. The UASG’s naming and storage policy for the documents will be: * Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document This proposal seems to adopt a number and reject Asmus' proposal for a short title phrase as the consistent reference name. I see the value of having a document number, but I think having a consistent short title phrase is also valuable. * Document Revision – (e.g. UASG000 – 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. I like using a date in yyyy-mm-dd format as a document revision code. * Document Link – (e.g. English https://uasg.tech/wp-content/uploads/UASG-000-Inventory-of-Material.pdf ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. I have reservations about embedding text like "wp-content/uploads/" in the official document link for our documents. It seems to be an artifact of our current website technology, which has no place in the official link. I would suggest a link authored solely for being a clear reference, e.g. https://uasg.tech/publications/UASG000-Inventory-of-Material/ If we are using document numbers, we should use them consistency. Note "UASG-000" in the proposed document link differs from "UASG000", the proposed document number. They should be the same. It might be good to insert a language code in our URLs. I hope in good time we will have our website and our important publications in several different languages. The document link might be, https://uasg.tech/en/publications/UASG000-Inventory-of-Material/ The same document can be published in different formats. Additionally, there is a need to refer to metadata about the document. Metadata includes: a list of links to different revisions of the document, a list of links to different language versions of the same document, an abstract, revision details, and so on. So, I propose we make a Document Link structure which can consistently refer to: * the PDF representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.pdf, * the HTML representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.html, * the HTML representation of metadata revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material, * the (PDF or other format) representation of a specific revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material/2019-01-24/U..., * all of the above in a different language, e.g. https://uasg.tech/ja/文書/UASG000-文書一覧.pdf [Example only; I am not a skilled speaker of Japanese, I probably made bad choices for the translation into Japanese. —Jim] * Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) Agreed. I am proposing that one link to the deprecated version of documents be in the metadata page for that document, and that our document link convention specify the document link format for deprecated versions also. * Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done. Agreed. I am also proposing that the metadata page for a document include a summary of revisions, even for brochures. Other comments? —Jim DeLaHunt, Vancouver, Canada From: UA-discuss <ua-discuss-bounces@icann.org><mailto:ua-discuss-bounces@icann.org> On Behalf Of Asmus Freytag (c) Sent: Wednesday, 9 January 2019 2:09 PM To: Mike Hemp <mikehamp1971@mail.com><mailto:mikehamp1971@mail.com> Cc: ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents On 1/8/2019 3:58 PM, Mike Hemp wrote: For the god sake do not make it complicated for people. RFC/IETF is only for highly technical community not for website and general application developers. Keep complications behind and keep the things simple for general audience. UASG is for everyone and must be understood very easily. Asmus idea is great. Get rid of numbers please. People who make money from technical stuff make issues complicated and would come up with such ideas. W3C manages without numbers. But that requires short names like "CSS" or "HTML" or something. Having to always cite documents by a full title like "email address internationalization EAI a technical_overview" gets pretty old. However, changing the title around a bit to something like EAI Overview: Email Address Internationalization (EAI), would allow "EAI Oveview" or "UASG EAI Overview" as shorthand, which arguably would be more self-explanatory than UASG 02. A./ Sent: Wednesday, January 09, 2019 at 3:01 AM From: "Asmus Freytag" <asmusf@ix.netcom.com><mailto:asmusf@ix.netcom.com> To: ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents For comparison, the Unicode Standard has the model where a link generally would get you the latest version of a document, but each document contains a header with a link to the previous revision of the document. That way, if you want to point people to the latest version of a document you can use an "evergreen" link, but if you need to be sure that the link goes to a specific version, there's that option as well. http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... or http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would get the latest version and http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would be a specific version. Each version remaining unaltered once posted. A./ On 1/8/2019 12:54 PM, Jim DeLaHunt wrote: UA Colleagues: I think the problem Michael points out is a real one, and worthy of attention. On 2019-01-08 07:03, Michael Casadevall wrote: So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision. One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted.... Michael proposes one alternative, …to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.… Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview". Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite. I believe we should also define standard, persistent URLs for each document, something like: http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time. Best regard, —Jim DeLaHunt, Vancouver, Canada -- --Jim DeLaHunt, jdlh@jdlh.com<mailto:jdlh@jdlh.com> http://blog.jdlh.com/ (http://jdlh.com/) multilingual websites consultant 355-1027 Davie St, Vancouver BC V6E 4L2, Canada Canada mobile +1-604-376-8953
I agree with Jim, Dennis and Asmus comments. I don’t understand why Asmus disagrees with Jim’s reservation about referencing the technology in the path. I think the technology is irrelevant and unnecessary and likely to change over time so should not be included. Also, I would caution on the original proposal presuming that with a change in language that the short title would change. It is possible for short titles, that the text would not change when the language changes, so that it would not be distinct. The path should include an explicit language indicator, preferably using the iso language code or the fuller BCP47 code. It is not clear to me that the language should “always” be a directory as Jim proposed. We should have a mechanism for users to indicate their preferred language without it being explicit in the path. As with document versioning with dates in the name, I think language can be in the path (or in the name) but it shouldn’t be a requirement for more general retrieval of the document. In offering multiple languages, we need to indicate if the translation(s) reflect the latest version of the document as there may be delays in availability. We also need a way to indicate which languages are available if the same translations are not available for all documents. We need to state how fallbacking will be addressed. Perhaps the handling for translations should be taken up as a separate thread so as not to impede this proposal for document handling. Also, I would like to see a naming convention for distinguishing drafts from official publications. We need a mechanism for offering and reviewing draft versions. Perhaps in an alternative directory, for ease of discovery. https://uasg.tech/en/drafts/UASG000-Inventory-of-Material tex From: UA-discuss [mailto:ua-discuss-bounces@icann.org] On Behalf Of Asmus Freytag Sent: Thursday, January 24, 2019 2:20 PM To: ua-discuss@icann.org Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents All, the virtue of a document number is that it makes it easier to correlate translations and give each document a translated name. That might outweigh the downside of having it so prominent in the first place. Jim's comment about consistent punctuation in document numbering is spot on. I also like to second his suggestion for structuring the path. A./ PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation. On 1/24/2019 12:26 PM, Jim DeLaHunt wrote: UASG Colleagues: [keeping list address, dropping redundant individual addresses] I'm glad to see this discussion moving towards a convention which addresses some of the issues raised. Some comments on Don's proposal interleaved below. On 2019-01-24 08:23, Don Hollander wrote: Thanks for comments. Here’s my proposal Document Naming and Storage Conventions
From time to time the UASG will review and revise documents. The UASG’s naming and storage policy for the documents will be:
* Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document This proposal seems to adopt a number and reject Asmus' proposal for a short title phrase as the consistent reference name. I see the value of having a document number, but I think having a consistent short title phrase is also valuable. * Document Revision – (e.g. UASG000 – 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. I like using a date in yyyy-mm-dd format as a document revision code. * Document Link – (e.g. English https://uasg.tech/wp-content/uploads/UASG-000-Inventory-of-Material.pdf ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. I have reservations about embedding text like "wp-content/uploads/" in the official document link for our documents. It seems to be an artifact of our current website technology, which has no place in the official link. I would suggest a link authored solely for being a clear reference, e.g. https://uasg.tech/publications/UASG000-Inventory-of-Material/ If we are using document numbers, we should use them consistency. Note "UASG-000" in the proposed document link differs from "UASG000", the proposed document number. They should be the same. It might be good to insert a language code in our URLs. I hope in good time we will have our website and our important publications in several different languages. The document link might be, https://uasg.tech/en/publications/UASG000-Inventory-of-Material/ The same document can be published in different formats. Additionally, there is a need to refer to metadata about the document. Metadata includes: a list of links to different revisions of the document, a list of links to different language versions of the same document, an abstract, revision details, and so on. So, I propose we make a Document Link structure which can consistently refer to: * the PDF representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.pdf, * the HTML representation of a current revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material.html, * the HTML representation of metadata revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material, * the (PDF or other format) representation of a specific revision of a document, e.g. https://uasg.tech/en/publications/UASG000-Inventory-of-Material/2019-01-24/U..., * all of the above in a different language, e.g. https://uasg.tech/ja/ <https://uasg.tech/ja/文書/UASG000-文書一覧.pdf> 文書/UASG000-文書一覧.pdf [Example only; I am not a skilled speaker of Japanese, I probably made bad choices for the translation into Japanese. —Jim] * Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) Agreed. I am proposing that one link to the deprecated version of documents be in the metadata page for that document, and that our document link convention specify the document link format for deprecated versions also. * Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done. Agreed. I am also proposing that the metadata page for a document include a summary of revisions, even for brochures. Other comments? —Jim DeLaHunt, Vancouver, Canada From: UA-discuss <mailto:ua-discuss-bounces@icann.org> <ua-discuss-bounces@icann.org> On Behalf Of Asmus Freytag (c) Sent: Wednesday, 9 January 2019 2:09 PM To: Mike Hemp <mailto:mikehamp1971@mail.com> <mikehamp1971@mail.com> Cc: ua-discuss@icann.org Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents On 1/8/2019 3:58 PM, Mike Hemp wrote: For the god sake do not make it complicated for people. RFC/IETF is only for highly technical community not for website and general application developers. Keep complications behind and keep the things simple for general audience. UASG is for everyone and must be understood very easily. Asmus idea is great. Get rid of numbers please. People who make money from technical stuff make issues complicated and would come up with such ideas. W3C manages without numbers. But that requires short names like "CSS" or "HTML" or something. Having to always cite documents by a full title like "email address internationalization EAI a technical_overview" gets pretty old. However, changing the title around a bit to something like EAI Overview: Email Address Internationalization (EAI), would allow "EAI Oveview" or "UASG EAI Overview" as shorthand, which arguably would be more self-explanatory than UASG 02. A./ Sent: Wednesday, January 09, 2019 at 3:01 AM From: "Asmus Freytag" <mailto:asmusf@ix.netcom.com> <asmusf@ix.netcom.com> To: ua-discuss@icann.org Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents For comparison, the Unicode Standard has the model where a link generally would get you the latest version of a document, but each document contains a header with a link to the previous revision of the document. That way, if you want to point people to the latest version of a document you can use an "evergreen" link, but if you need to be sure that the link goes to a specific version, there's that option as well. http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... or http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would get the latest version and http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... would be a specific version. Each version remaining unaltered once posted. A./ On 1/8/2019 12:54 PM, Jim DeLaHunt wrote: UA Colleagues: I think the problem Michael points out is a real one, and worthy of attention. On 2019-01-08 07:03, Michael Casadevall wrote: So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision. One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted.... Michael proposes one alternative, …to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.… Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview". Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite. I believe we should also define standard, persistent URLs for each document, something like: http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t... and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time. Best regard, —Jim DeLaHunt, Vancouver, Canada -- --Jim DeLaHunt, jdlh@jdlh.com http://blog.jdlh.com/ (http://jdlh.com/) multilingual websites consultant 355-1027 Davie St, Vancouver BC V6E 4L2, Canada Canada mobile +1-604-376-8953
On 1/24/2019 2:55 PM, Tex wrote:
PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation.
This was about whether revisions are documented inside the document. Don, suggested not, and I would agree. I think of brochures as a type of document, not a technology, but may have misunderstood something. A./
Thanks for the clarification Asmus. I agree with you, brochures shouldn’t have revision histories. I had noticed the one place where Jim used the word “reservation” and thought your second sentence was independent from the first, and commenting on that- “I have reservations about embedding text like "wp-content/uploads/" in the official document link” So it’s all good. Tex From: UA-discuss [mailto:ua-discuss-bounces@icann.org] On Behalf Of Asmus Freytag Sent: Thursday, January 24, 2019 4:10 PM To: ua-discuss@icann.org Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents On 1/24/2019 2:55 PM, Tex wrote: PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation. This was about whether revisions are documented inside the document. Don, suggested not, and I would agree. I think of brochures as a type of document, not a technology, but may have misunderstood something. A./
Thanks. How’s this? * Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document. NB: No hyphen in the document number. * Document Short Title (e.g. UASG000 Inventory of Material) – this will be included in the file name. * Document Language (e.g. UASG000 Inventory of Material EN) – this will be included in the file name. * Document Revision – (e.g. UASG000 Inventory of Material EN 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. * Document Link – (e.g. https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf<https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...> ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. * Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) * Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done. Revision Notes: 2019-01-25 Added Document Naming and Storage Conventions 2018-12-25 Added expected review dates From: UA-discuss <ua-discuss-bounces@icann.org> On Behalf Of Tex Sent: Friday, 25 January 2019 1:23 PM To: 'Asmus Freytag' <asmusf@ix.netcom.com>; ua-discuss@icann.org Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents Thanks for the clarification Asmus. I agree with you, brochures shouldn’t have revision histories. I had noticed the one place where Jim used the word “reservation” and thought your second sentence was independent from the first, and commenting on that- “I have reservations about embedding text like "wp-content/uploads/" in the official document link” So it’s all good. Tex From: UA-discuss [mailto:ua-discuss-bounces@icann.org] On Behalf Of Asmus Freytag Sent: Thursday, January 24, 2019 4:10 PM To: ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents On 1/24/2019 2:55 PM, Tex wrote: PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation. This was about whether revisions are documented inside the document. Don, suggested not, and I would agree. I think of brochures as a type of document, not a technology, but may have misunderstood something. A./
I would expect to be able to leave the date off the link and get the /*latest */file version. Depending on technology that gets implemented with soft link, redirection or duplicate copy, but for the user, that is immaterial, all that counts is being able to ignore the revision date. I would expect each document to carry such a generic link to the "latest" version in a header or a note somehwere, so that no matter what copy of the document you are accessing (based some reference somewhere) you are always able to discover the existence of later versions. I would expect the revision notes to have a link for each date, so one can backtrack versions without going through the archive. Otherwise, this is beginning to take shape. A./ On 1/24/2019 9:45 PM, Don Hollander wrote:
Thanks.
How’s this?
* Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document. NB: No hyphen in the document number. * Document Short Title (e.g. UASG000 Inventory of Material) – this will be included in the file name. * Document Language (e.g. UASG000 Inventory of Material EN) – this will be included in the file name. * Document Revision – (e.g. UASG000 Inventory of Material EN 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. * Document Link – (e.g. https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf <https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...> ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. * Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) * Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done.
Revision Notes:
2019-01-25
Added Document Naming and Storage Conventions
2018-12-25
Added expected review dates
*From:*UA-discuss <ua-discuss-bounces@icann.org> *On Behalf Of *Tex *Sent:* Friday, 25 January 2019 1:23 PM *To:* 'Asmus Freytag' <asmusf@ix.netcom.com>; ua-discuss@icann.org *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents
Thanks for the clarification Asmus. I agree with you, brochures shouldn’t have revision histories.
I had noticed the one place where Jim used the word “reservation” and thought your second sentence was independent from the first, and commenting on that-
“I have reservations about embedding text like "wp-content/uploads/" in the official document link”
So it’s all good.
Tex
*From:*UA-discuss [mailto:ua-discuss-bounces@icann.org] *On Behalf Of *Asmus Freytag *Sent:* Thursday, January 24, 2019 4:10 PM *To:* ua-discuss@icann.org <mailto:ua-discuss@icann.org> *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents
On 1/24/2019 2:55 PM, Tex wrote:
PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation.
This was about whether revisions are documented inside the document. Don, suggested not, and I would agree. I think of brochures as a type of document, not a technology, but may have misunderstood something.
A./
So you would want the main link to be: https://uasg.tech/documents/UASG000-Inventory-of-Material EN.pdf <https://uasg.tech/documents/UASG000-Inventory-of-Material%20EN.pdf> And the filename to be https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf <https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...> From: UA-discuss <ua-discuss-bounces@icann.org> On Behalf Of Asmus Freytag (c) Sent: Friday, 25 January 2019 7:30 PM To: Don Hollander <don.hollander@icann.org>; Tex <textexin@xencraft.com>; ua-discuss@icann.org Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents I would expect to be able to leave the date off the link and get the latest file version. Depending on technology that gets implemented with soft link, redirection or duplicate copy, but for the user, that is immaterial, all that counts is being able to ignore the revision date. I would expect each document to carry such a generic link to the "latest" version in a header or a note somehwere, so that no matter what copy of the document you are accessing (based some reference somewhere) you are always able to discover the existence of later versions. I would expect the revision notes to have a link for each date, so one can backtrack versions without going through the archive. Otherwise, this is beginning to take shape. A./ On 1/24/2019 9:45 PM, Don Hollander wrote: Thanks. How’s this? * Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document. NB: No hyphen in the document number. * Document Short Title (e.g. UASG000 Inventory of Material) – this will be included in the file name. * Document Language (e.g. UASG000 Inventory of Material EN) – this will be included in the file name. * Document Revision – (e.g. UASG000 Inventory of Material EN 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. * Document Link – (e.g. https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf <https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...> ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. * Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) * Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done. Revision Notes: 2019-01-25 Added Document Naming and Storage Conventions 2018-12-25 Added expected review dates From: UA-discuss <mailto:ua-discuss-bounces@icann.org> <ua-discuss-bounces@icann.org> On Behalf Of Tex Sent: Friday, 25 January 2019 1:23 PM To: 'Asmus Freytag' <mailto:asmusf@ix.netcom.com> <asmusf@ix.netcom.com>; ua-discuss@icann.org <mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents Thanks for the clarification Asmus. I agree with you, brochures shouldn’t have revision histories. I had noticed the one place where Jim used the word “reservation” and thought your second sentence was independent from the first, and commenting on that- “I have reservations about embedding text like "wp-content/uploads/" in the official document link” So it’s all good. Tex From: UA-discuss [mailto:ua-discuss-bounces@icann.org] On Behalf Of Asmus Freytag Sent: Thursday, January 24, 2019 4:10 PM To: ua-discuss@icann.org <mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents On 1/24/2019 2:55 PM, Tex wrote: PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation. This was about whether revisions are documented inside the document. Don, suggested not, and I would agree. I think of brochures as a type of document, not a technology, but may have misunderstood something. A./
On 1/24/2019 10:55 PM, Don Hollander wrote:
So you would want the main link to be:
https://uasg.tech/documents/UASG000-Inventory-of-Material EN.pdf <https://uasg.tech/documents/UASG000-Inventory-of-Material%20EN.pdf>
And the filename to be
https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf <https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...>
Yep. For Unicode, the main link for technical reports even drops the file extension (usually html for TRs), so in your example: https://uasg.tech/documents/UASG000-Inventory-of-Material EN <https://uasg.tech/documents/UASG000-Inventory-of-Material%20EN.pdf> if that can be realized. (Unicode, the way they do it, piggybacks on the "index.html" technique which would not be apropos here, so if the extension has to be retained it's not that critical). A,/ PS: I find file names with spaces are still a pain for some tools, so I suggest adding some hyphens.
*From:*UA-discuss <ua-discuss-bounces@icann.org> *On Behalf Of *Asmus Freytag (c) *Sent:* Friday, 25 January 2019 7:30 PM *To:* Don Hollander <don.hollander@icann.org>; Tex <textexin@xencraft.com>; ua-discuss@icann.org *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents
I would expect to be able to leave the date off the link and get the */latest /*file version. Depending on technology that gets implemented with soft link, redirection or duplicate copy, but for the user, that is immaterial, all that counts is being able to ignore the revision date.
I would expect each document to carry such a generic link to the "latest" version in a header or a note somehwere, so that no matter what copy of the document you are accessing (based some reference somewhere) you are always able to discover the existence of later versions.
I would expect the revision notes to have a link for each date, so one can backtrack versions without going through the archive.
Otherwise, this is beginning to take shape.
A./
On 1/24/2019 9:45 PM, Don Hollander wrote:
Thanks.
How’s this?
* Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document. NB: No hyphen in the document number. * Document Short Title (e.g. UASG000 Inventory of Material) – this will be included in the file name. * Document Language (e.g. UASG000 Inventory of Material EN) – this will be included in the file name. * Document Revision – (e.g. UASG000 Inventory of Material EN 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. * Document Link – (e.g. https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf <https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...> ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. * Archives: The UASG.tech website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) * Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done.
Revision Notes:
2019-01-25
Added Document Naming and Storage Conventions
2018-12-25
Added expected review dates
*From:*UA-discuss <ua-discuss-bounces@icann.org> <mailto:ua-discuss-bounces@icann.org> *On Behalf Of *Tex *Sent:* Friday, 25 January 2019 1:23 PM *To:* 'Asmus Freytag' <asmusf@ix.netcom.com> <mailto:asmusf@ix.netcom.com>; ua-discuss@icann.org <mailto:ua-discuss@icann.org> *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents
Thanks for the clarification Asmus. I agree with you, brochures shouldn’t have revision histories.
I had noticed the one place where Jim used the word “reservation” and thought your second sentence was independent from the first, and commenting on that-
“I have reservations about embedding text like "wp-content/uploads/" in the official document link”
So it’s all good.
Tex
*From:*UA-discuss [mailto:ua-discuss-bounces@icann.org] *On Behalf Of *Asmus Freytag *Sent:* Thursday, January 24, 2019 4:10 PM *To:* ua-discuss@icann.org <mailto:ua-discuss@icann.org> *Subject:* Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents
On 1/24/2019 2:55 PM, Tex wrote:
PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation.
This was about whether revisions are documented inside the document. Don, suggested not, and I would agree. I think of brochures as a type of document, not a technology, but may have misunderstood something.
A./
On 25 Jan 2019, at 07:18, Asmus Freytag (c) <asmusf@ix.netcom.com<mailto:asmusf@ix.netcom.com>> wrote: On 1/24/2019 10:55 PM, Don Hollander wrote: So you would want the main link to be: https://uasg.tech/documents/UASG000-Inventory-of-Material EN.pdf<https://uasg.tech/documents/UASG000-Inventory-of-Material%20EN.pdf> And the filename to be https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf<https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...> Yep. For Unicode, the main link for technical reports even drops the file extension (usually html for TRs), so in your example: https://uasg.tech/documents/UASG000-Inventory-of-Material EN<https://uasg.tech/documents/UASG000-Inventory-of-Material%20EN.pdf> if that can be realized. (Unicode, the way they do it, piggybacks on the "index.html" technique which would not be apropos here, so if the extension has to be retained it's not that critical). A,/ PS: I find file names with spaces are still a pain for some tools, so I suggest adding some hyphens. Why not have the filenames in the language of the document thus giving a link such as: uasg.tech/documents/UASG000-инвентарь-материала<http://uasg.tech/documents/UASG000-инвентарь-материала> or uasg.tech/documents/UASG000-инвентарь-материала-2019-01-25 I have purposely dropped the language tag ru as a person who understands Russian would understand the filename in the link. This is inline with the common practice on websites for the language names to be written in that language and script eg wikipedia and twitter I know it adds complications but I consider it much more in the spirit of internationalisation. André Schappo From: UA-discuss <ua-discuss-bounces@icann.org><mailto:ua-discuss-bounces@icann.org> On Behalf Of Asmus Freytag (c) Sent: Friday, 25 January 2019 7:30 PM To: Don Hollander <don.hollander@icann.org><mailto:don.hollander@icann.org>; Tex <textexin@xencraft.com><mailto:textexin@xencraft.com>; ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents I would expect to be able to leave the date off the link and get the latest file version. Depending on technology that gets implemented with soft link, redirection or duplicate copy, but for the user, that is immaterial, all that counts is being able to ignore the revision date. I would expect each document to carry such a generic link to the "latest" version in a header or a note somehwere, so that no matter what copy of the document you are accessing (based some reference somewhere) you are always able to discover the existence of later versions. I would expect the revision notes to have a link for each date, so one can backtrack versions without going through the archive. Otherwise, this is beginning to take shape. A./ On 1/24/2019 9:45 PM, Don Hollander wrote: Thanks. How’s this? * Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document. NB: No hyphen in the document number. * Document Short Title (e.g. UASG000 Inventory of Material) – this will be included in the file name. * Document Language (e.g. UASG000 Inventory of Material EN) – this will be included in the file name. * Document Revision – (e.g. UASG000 Inventory of Material EN 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. * Document Link – (e.g. https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf<https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...> ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. * Archives: The UASG.tech<http://uasg.tech/> website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) * Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done. Revision Notes: 2019-01-25 Added Document Naming and Storage Conventions 2018-12-25 Added expected review dates From: UA-discuss <ua-discuss-bounces@icann.org><mailto:ua-discuss-bounces@icann.org> On Behalf Of Tex Sent: Friday, 25 January 2019 1:23 PM To: 'Asmus Freytag' <asmusf@ix.netcom.com><mailto:asmusf@ix.netcom.com>; ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents Thanks for the clarification Asmus. I agree with you, brochures shouldn’t have revision histories. I had noticed the one place where Jim used the word “reservation” and thought your second sentence was independent from the first, and commenting on that- “I have reservations about embedding text like "wp-content/uploads/" in the official document link” So it’s all good. Tex From: UA-discuss [mailto:ua-discuss-bounces@icann.org] On Behalf Of Asmus Freytag Sent: Thursday, January 24, 2019 4:10 PM To: ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents On 1/24/2019 2:55 PM, Tex wrote: PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation. This was about whether revisions are documented inside the document. Don, suggested not, and I would agree. I think of brochures as a type of document, not a technology, but may have misunderstood something. A./ 🌏 🌍 🌎 André Schappo 小山@电邮.在线?Subject=你好小山😜<mailto:%E5%B0%8F%E5%B1%B1@%E7%94%B5%E9%82%AE.%E5%9C%A8%E7%BA%BF?Subject=%E4%BD%A0%E5%A5%BD%E5%B0%8F%E5%B1%B1%F0%9F%98%9C> schappo.blogspot.co.uk<https://schappo.blogspot.co.uk> twitter.com/andreschappo<https://twitter.com/andreschappo> weibo.com/andreschappo?is_all=1<https://weibo.com/andreschappo?is_all=1> groups.google.com/forum/#!forum/computer-science-curriculum-internationalization<https://groups.google.com/forum/#!forum/computer-science-curriculum-internat...>
On 25 Jan 2019, at 10:50, Andre Schappo <A.Schappo@lboro.ac.uk<mailto:A.Schappo@lboro.ac.uk>> wrote: On 25 Jan 2019, at 07:18, Asmus Freytag (c) <asmusf@ix.netcom.com<mailto:asmusf@ix.netcom.com>> wrote: On 1/24/2019 10:55 PM, Don Hollander wrote: So you would want the main link to be: https://uasg.tech/documents/UASG000-Inventory-of-Material EN.pdf<https://uasg.tech/documents/UASG000-Inventory-of-Material%20EN.pdf> And the filename to be https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf<https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...> Yep. For Unicode, the main link for technical reports even drops the file extension (usually html for TRs), so in your example: https://uasg.tech/documents/UASG000-Inventory-of-Material EN<https://uasg.tech/documents/UASG000-Inventory-of-Material%20EN.pdf> if that can be realized. (Unicode, the way they do it, piggybacks on the "index.html" technique which would not be apropos here, so if the extension has to be retained it's not that critical). A,/ PS: I find file names with spaces are still a pain for some tools, so I suggest adding some hyphens. Why not have the filenames in the language of the document thus giving a link such as: uasg.tech/documents/UASG000-инвентарь-материала<http://uasg.tech/documents/UASG000-%D0%B8%D0%BD%D0%B2%D0%B5%D0%BD%D1%82%D0%B...> or uasg.tech/documents/UASG000-инвентарь-материала-2019-01-25<http://uasg.tech/documents/UASG000-инвентарь-материала-2019-01-25> I have purposely dropped the language tag ru as a person who understands Russian would understand the filename in the link. This is inline with the common practice on websites for the language names to be written in that language and script eg wikipedia and twitter eg wikipedia and twitter and UASG uasg.tech/documents<https://uasg.tech/documents/> I know it adds complications but I consider it much more in the spirit of internationalisation. André Schappo From: UA-discuss <ua-discuss-bounces@icann.org><mailto:ua-discuss-bounces@icann.org> On Behalf Of Asmus Freytag (c) Sent: Friday, 25 January 2019 7:30 PM To: Don Hollander <don.hollander@icann.org><mailto:don.hollander@icann.org>; Tex <textexin@xencraft.com><mailto:textexin@xencraft.com>; ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents I would expect to be able to leave the date off the link and get the latest file version. Depending on technology that gets implemented with soft link, redirection or duplicate copy, but for the user, that is immaterial, all that counts is being able to ignore the revision date. I would expect each document to carry such a generic link to the "latest" version in a header or a note somehwere, so that no matter what copy of the document you are accessing (based some reference somewhere) you are always able to discover the existence of later versions. I would expect the revision notes to have a link for each date, so one can backtrack versions without going through the archive. Otherwise, this is beginning to take shape. A./ On 1/24/2019 9:45 PM, Don Hollander wrote: Thanks. How’s this? * Document Number (e.g. UASG000) – this will be maintained as a consistent reference name for a document. NB: No hyphen in the document number. * Document Short Title (e.g. UASG000 Inventory of Material) – this will be included in the file name. * Document Language (e.g. UASG000 Inventory of Material EN) – this will be included in the file name. * Document Revision – (e.g. UASG000 Inventory of Material EN 2019-01-25) This will be based on the publication date and represented in the file name as yyyy-mm-dd. It will also be included within the document. * Document Link – (e.g. https://uasg.tech/documents/UASG000-Inventory-of-Material EN 2019 01 25.pdf<https://uasg.tech/documents/UASG-000-Inventory-of-Material%20EN%202019%2001%...> ) This will be based on the language of the document and is what’s published on the UASG.Tech website and will retrieve the latest official version of the document. * Archives: The UASG.tech<http://uasg.tech/> website will include a repository of deprecated versions of documents that will be stored and displayed based on its file name (which will include the published date) * Revision Details: For most documents we will maintain a table at the end showing a summary of revisions. Where a document is used a brochure, this will not be done. Revision Notes: 2019-01-25 Added Document Naming and Storage Conventions 2018-12-25 Added expected review dates From: UA-discuss <ua-discuss-bounces@icann.org><mailto:ua-discuss-bounces@icann.org> On Behalf Of Tex Sent: Friday, 25 January 2019 1:23 PM To: 'Asmus Freytag' <asmusf@ix.netcom.com><mailto:asmusf@ix.netcom.com>; ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents Thanks for the clarification Asmus. I agree with you, brochures shouldn’t have revision histories. I had noticed the one place where Jim used the word “reservation” and thought your second sentence was independent from the first, and commenting on that- “I have reservations about embedding text like "wp-content/uploads/" in the official document link” So it’s all good. Tex From: UA-discuss [mailto:ua-discuss-bounces@icann.org] On Behalf Of Asmus Freytag Sent: Thursday, January 24, 2019 4:10 PM To: ua-discuss@icann.org<mailto:ua-discuss@icann.org> Subject: Re: [UA-discuss] Proposal: Handling Numbering of the UASG Documents On 1/24/2019 2:55 PM, Tex wrote: PS: Brochures, by their nature are different from the kind of reports and formal documents that need careful version tracking in the document. I disagree with Jim on his reservation. This was about whether revisions are documented inside the document. Don, suggested not, and I would agree. I think of brochures as a type of document, not a technology, but may have misunderstood something. A./ 🌏 🌍 🌎 André Schappo 小山@电邮.在线?Subject=你好小山😜<mailto:%E5%B0%8F%E5%B1%B1@%E7%94%B5%E9%82%AE.%E5%9C%A8%E7%BA%BF?Subject=%E4%BD%A0%E5%A5%BD%E5%B0%8F%E5%B1%B1%F0%9F%98%9C> schappo.blogspot.co.uk<https://schappo.blogspot.co.uk/> twitter.com/andreschappo<https://twitter.com/andreschappo> weibo.com/andreschappo?is_all=1<https://weibo.com/andreschappo?is_all=1> groups.google.com/forum/#!forum/computer-science-curriculum-internationalization<https://groups.google.com/forum/#!forum/computer-science-curriculum-internat...> 🌏 🌍 🌎 André Schappo 小山@电邮.在线?Subject=你好小山😜<mailto:%E5%B0%8F%E5%B1%B1@%E7%94%B5%E9%82%AE.%E5%9C%A8%E7%BA%BF?Subject=%E4%BD%A0%E5%A5%BD%E5%B0%8F%E5%B1%B1%F0%9F%98%9C> schappo.blogspot.co.uk<https://schappo.blogspot.co.uk> twitter.com/andreschappo<https://twitter.com/andreschappo> weibo.com/andreschappo?is_all=1<https://weibo.com/andreschappo?is_all=1> groups.google.com/forum/#!forum/computer-science-curriculum-internationalization<https://groups.google.com/forum/#!forum/computer-science-curriculum-internat...>
In article <796AD1B9-EF75-4FF9-BDDF-2C8F249BF10E@lboro.ac.uk> you write:
So you would want the main link to be:
https://uasg.tech/documents/UASG000-Inventory-of-Material EN.pdf<https://uasg.tech/documents/UASG000-Inventory-of-Material%20EN.pdf>
FYI, there is no need for the URL to end with .pdf or .html to indicate the content type. Web servers have other ways to do that.
PS: I find file names with spaces are still a pain for some tools, so I suggest adding some hyphens.
Agreed.
Why not have the filenames in the language of the document thus giving a link such as: uasg.tech/documents/UASG000-инвентарь-материала<http://uasg.tech/documents/UASG000-%D0%B8%D0%BD%D0%B2%D0%B5%D0%BD%D1%82%D0%B...> or uasg.tech/documents/UASG000-инвентарь-материала-2019-01-25<http://uasg.tech/documents/UASG000-инвентарь-материала-2019-01-25>
In principle a reasonable idea, in practice UTF-8 in URLs can be flaky. Some browsers hex encode it, some don't. R's, John
On 25 Jan 2019, at 17:23, John Levine <john.levine@standcore.com> wrote:
In article <796AD1B9-EF75-4FF9-BDDF-2C8F249BF10E@lboro.ac.uk> you write:
So you would want the main link to be:
https://uasg.tech/documents/UASG000-Inventory-of-Material EN.pdf<https://uasg.tech/documents/UASG000-Inventory-of-Material%20EN.pdf>
FYI, there is no need for the URL to end with .pdf or .html to indicate the content type. Web servers have other ways to do that.
PS: I find file names with spaces are still a pain for some tools, so I suggest adding some hyphens.
Agreed.
Why not have the filenames in the language of the document thus giving a link such as: uasg.tech/documents/UASG000-инвентарь-материала<http://uasg.tech/documents/UASG000-%D0%B8%D0%BD%D0%B2%D0%B5%D0%BD%D1%82%D0%B...> or uasg.tech/documents/UASG000-инвентарь-материала-2019-01-25<http://uasg.tech/documents/UASG000-инвентарь-материала-2019-01-25>
In principle a reasonable idea, in practice UTF-8 in URLs can be flaky. Some browsers hex encode it, some don't.
I think it in the nature of UASG to be involved in the flaky areas and to tackle those flaky areas head on. I suppose strictly speaking UASG is only involved in IDNs and EAI but it is rather difficult to ignore Unicode URLs (ie with a Part/Full Unicode pathname and Unicode/ASCII domain name). So I think we should not avoid the issue and so I vote for using such Unicode URLs on the UASG website. Yes there are and will be problems but letʼs use them, highlight them and tackle them head on. André Schappo
R's, John
In article <8E45C5AE-FD2F-40B1-872E-540D6ECBFC72@lboro.ac.uk> you write:
I think it in the nature of UASG to be involved in the flaky areas and to tackle those flaky areas head on. I suppose strictly speaking UASG is only involved in IDNs and EAI but it is rather difficult to ignore Unicode URLs (ie with a Part/Full Unicode pathname and Unicode/ASCII domain name). So I think we should not avoid the issue and so I vote for using such Unicode URLs on the UASG website. Yes there are and will be problems but letʼs use them, highlight them and tackle them head on.
How do you propose to tackle this problem? It's unresolved at the standards level and the IETF has been scratching its head about what to do. -- Regards, John Levine, johnl@iecc.com, Primary Perpetrator of "The Internet for Dummies", Please consider the environment before reading this e-mail. https://jl.ly
On 28 Jan 2019, at 19:19, John Levine <john.levine@standcore.com> wrote:
In article <8E45C5AE-FD2F-40B1-872E-540D6ECBFC72@lboro.ac.uk> you write:
I think it in the nature of UASG to be involved in the flaky areas and to tackle those flaky areas head on. I suppose strictly speaking UASG is only involved in IDNs and EAI but it is rather difficult to ignore Unicode URLs (ie with a Part/Full Unicode pathname and Unicode/ASCII domain name). So I think we should not avoid the issue and so I vote for using such Unicode URLs on the UASG website. Yes there are and will be problems but letʼs use them, highlight them and tackle them head on.
How do you propose to tackle this problem? It's unresolved at the standards level and the IETF has been scratching its head about what to do.
Ah😀 I do not have a solution or a proposal for a standard but I will certainly give it some thought. André Schappo
-- Regards, John Levine, johnl@iecc.com, Primary Perpetrator of "The Internet for Dummies", Please consider the environment before reading this e-mail. https://jl.ly
+1 to Jim's suggestions here. There needs to be a place to get "the latest version" and there needs to be a way to get "this version". W3C tends to do this well for its specs (until they get to versioning, at which they are not very good). IETF rather less so. chaals On Tue, 08 Jan 2019 21:54:02 +0100, Jim DeLaHunt <list+uasg@jdlh.com> wrote:
UA Colleagues:
I think the problem Michael points out is a real one, and worthy of attention.
On 2019-01-08 07:03, Michael Casadevall wrote:
So currently, the UASG publishes various documents such as UASG 0005 and 0007 and occasionally updates these documents to reflect best current practices. For example, the UA Quick Guide was on Version 9 before it was removed for revision.
One thing I'm concerned on is that it's not clear that a document has been updated, nor what has changed from version to version. Furthermore, when dealing with old discussions, a document may have changed from a message or posted.... Michael proposes one alternative, …to change the numbering and management of UASG documentation to model it around the RFC/IETF where a document is static once published (with errata linked), and is obsoleted/superseded by future documents.…
Another alternative is to keep the document number unchanged, but to have a clearly-defined revision date for each version of a document, and to always cite a revision date along with the document number. So, we would say "UASG012 Email Address Internationalization (EAI): A Technical Overview (v 2018-05-12)" instead of "UASG012" or "Email Address Internationalization (EAI): A Technical Overview".
Whichever we do, I believe we should set editorial standards that each document has a) document title, b) UASG number, and c) revision date clearly on the front cover and in the file name of each document issued. Looking through some existing documents, we seem to be inconsistent about this. It makes documents harder to find and harder to cite.
I believe we should also define standard, persistent URLs for each document, something like:
http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_t...
and ensure that visiting such a URL with a web browser returns either the document file itself, or a page describing the document and allowing one to download it. I find it hard to put links to UASG documents into presentations, because it's difficult to figure out which URL to use, and how much to trust it to stay usable over time.
Best regard, —Jim DeLaHunt, Vancouver, Canada
-- Using Opera's mail client: http://www.opera.com/mail/
participants (14)
-
Andre Schappo -
Asmus Freytag -
Asmus Freytag (c) -
Charles 'chaals' (McCathie) Nevile -
Don Hollander -
Don Hollander -
Jim DeLaHunt -
John Levine -
Michael Casadevall -
Mike Hemp -
Ram Mohan -
Richard Merdinger -
Tan Tanaka, Dennis -
Tex