[UA-discuss] Proposal: Handling Numbering of the UASG Documents
Asmus Freytag
asmusf at ix.netcom.com
Thu Jan 24 22:19:53 UTC 2019
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/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/dd85215d/attachment.html>
More information about the UA-discuss
mailing list