[UA-discuss] Proposal: Handling Numbering of the UASG Documents

Thu Jan 24 20:26:53 UTC 2019

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/UASG000-Inventory-of-Material.pdf,

  * 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 at icann.org> *On Behalf Of *Asmus 
> Freytag (c)
> *Sent:* Wednesday, 9 January 2019 2:09 PM
> *To:* Mike Hemp <mikehamp1971 at mail.com>
> *Cc:* ua-discuss at 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 at ix.netcom.com>
>     <mailto:asmusf at ix.netcom.com>
>     *To:* ua-discuss at icann.org <mailto:ua-discuss at 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_technical_overview/
>
>     or
>
>     http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_technical_overview/latest
>
>     would get the latest version and
>
>     http://uasg.tech/document/uasg012/email_address_internationalization_EAI_a_technical_overview/2018-05-12/
>
>     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_technical_overview/2018-05-12/
>
>         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 at 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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mm.icann.org/pipermail/ua-discuss/attachments/20190124/b435d7f2/attachment.html>