Re: authors.ietf.org now ready for review

Toerless Eckert <tte@cs.fau.de> Fri, 17 December 2021 17:03 UTC

Return-Path: <eckert@i4.informatik.uni-erlangen.de>
X-Original-To: wgchairs@ietfa.amsl.com
Delivered-To: wgchairs@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 805883A0824; Fri, 17 Dec 2021 09:03:18 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -0.869
X-Spam-Level:
X-Spam-Status: No, score=-0.869 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, HEADER_FROM_DIFFERENT_DOMAINS=0.25, SPF_HELO_NONE=0.001, SPF_NEUTRAL=0.779, URIBL_BLOCKED=0.001] autolearn=no autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id TpSnmWPwqHb4; Fri, 17 Dec 2021 09:03:13 -0800 (PST)
Received: from faui40.informatik.uni-erlangen.de (faui40.informatik.uni-erlangen.de [IPv6:2001:638:a000:4134::ffff:40]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 6C8B33A0812; Fri, 17 Dec 2021 09:03:10 -0800 (PST)
Received: from faui48e.informatik.uni-erlangen.de (faui48e.informatik.uni-erlangen.de [IPv6:2001:638:a000:4134::ffff:51]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by faui40.informatik.uni-erlangen.de (Postfix) with ESMTPS id 4AE2C549BA3; Fri, 17 Dec 2021 18:03:03 +0100 (CET)
Received: by faui48e.informatik.uni-erlangen.de (Postfix, from userid 10463) id 1B8694EA0C9; Fri, 17 Dec 2021 18:03:03 +0100 (CET)
Date: Fri, 17 Dec 2021 18:03:03 +0100
From: Toerless Eckert <tte@cs.fau.de>
To: Jay Daley <exec-director@ietf.org>
Cc: Working Chairs <wgchairs@ietf.org>
Subject: Re: authors.ietf.org now ready for review
Message-ID: <YbzCx8y53PRnNmhi@faui48e.informatik.uni-erlangen.de>
References: <96F1DCFE-276B-4A12-938D-6EB4C529CC15@ietf.org>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <96F1DCFE-276B-4A12-938D-6EB4C529CC15@ietf.org>
Archived-At: <https://mailarchive.ietf.org/arch/msg/wgchairs/zgpndzqNELJ4UMpwXq5xO9nSwKI>
X-BeenThere: wgchairs@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Working Group Chairs <wgchairs.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/wgchairs>, <mailto:wgchairs-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/wgchairs/>
List-Post: <mailto:wgchairs@ietf.org>
List-Help: <mailto:wgchairs-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/wgchairs>, <mailto:wgchairs-request@ietf.org?subject=subscribe>
X-List-Received-Date: Fri, 17 Dec 2021 17:03:19 -0000

Thanks a lot, Jay

I think this email by itself is something that would be great to
not simply misplace but easily find and refer to as it is the
best "quick start" for the new site.

Maybe put on the left side (blue list of selections),
maybe on the bottom a new selection "Updates" and then just
put into that section this and any further
update mails (with date). 

Cheers
    Toerless

On Fri, Dec 17, 2021 at 04:53:03PM +1300, Jay Daley wrote:
> For info, the following email has now gone to tools-discuss:
> 
> —— 
> # Context
> 
> At the end of 2020/start of 2021, the analysis of the survey of I-D authors recommended a new central resource site for I-D authors bringing together the documentation that is currently in multiple hard to find places, and we were given notice that the servers running tools.ietf.org would be turned off.  Consequently, work began in 2021 on a new site intended to be both that central resource and the new home for the documentation on tools.ietf.org. This site is now ready for community review at http://authors.ietf.org
> 
> The goals of this new site are:
> 
> - Bring all I-D authoring-related information into one place
> - Put that information into a structure that works equally well for novices, occasional authors and experts.
> - Ensure a full coverage of all the topics that authors need to know
> - Clear up the out of date, duplicate and incorrect information.
> 
> The content comes from the following sources:
> 
> - The catalog of tools on the front page of tools.ietf.org [0] with added categorisation and feature matrix
> - The xml2rfc vocabulary documentation [1] with added examples and schema snippets
> - Some pages on rfc-editor.org with relevant content [2] [3] [4]
> - The Guidelines for I-D authors [5]
> - New content to provide the necessary structure and fill any gaps.
> 
> This site is intended solely for I-D authors and so does not contain the following content:
> 
> - Details of the standards process
> - Documentation on the AUTH48 review and subsequent publication process as those are processes for RFCs not I-Ds.  This remains on rfc-editor.org 
> 
> 
> # Key changes
> 
> The site introduces the following key changes to the existing content:
> 
> 1.  What was previously referred to as "the xml2rfc vocabulary" is now referred to as RFCXML.  This is in line with the normal naming of XML languages and separates out the language from the tool, providing for independent implementations.  This change has been broadly supported by the RSOC, the Temporary RFC Series PM and the community tools developers who have been asked to preview the site.
> 
> 2.  The previous community supplied XML template has been replaced with three 'official' templates in order to:
> 
> - support modern XML editors that provide schema-aware editing
> - ensure that the template reflects best practice as expected by the RPC (e.g. using <sourcecode> for source code, not <artwork>)
> - provide different templates for different levels of expertise
> - reflect the schema and entity changes as noted below
> 
> The templates are:
> 
> 	draft-rfcxml-general-template-standard.xml
> 	draft-rfcxml-general-template-bare.xml
> 	draft-rfcxml-general-template-annotated.xml
> 
> These templates, together with the schemas are all available on the site [6] and in a GitHub repository [7] 
> 
> 3.  The schemas have been reorganised to more accurately reflect their contents and usage.  In particular ensuring that the name matches the contents and matches the RFC that defines those contents.
> 
> - rfc7991.rnc has not changed
> - v3.rnc has been renamed to rfc7991bis.rnc
> - v2.rnc has been renamed to rfc7749.rnc
> - rfc2629.dtd has had all references to it removed as it was effectively deprecated some time ago
> - rfc2629-html.ent and rfc2629-other.ent have been deprecated as special entity processing is not required in v3
> 
> The legacy schemas and associated files are all available in a single GitHub repository [8].
> 
> (In related news, the authors of rfc2629.xslt and kramdown-rfc2629 have agreed to rename their tools to remove the RFC-specific part which refers to v1 of RFCXML.)
> 
> 
> # Known issues
> 
> - In preparation for the migration of tools.ietf.org, some tool links point to placeholder repositories on GitHub rather than the current home for that tool.
> - Some links still point to tools.ietf.org 
> - There are a number of limitations in the underlying wiki product that are due to be addressed in upcoming versions:
>    - The site does not have an IETF look and feel.  This is 
>    - The page contents menu is automatically generated and placed and some people don’t like it.  
>    - Some checklist items render incorrectly.
> 
> 
> # Ongoing maintenance
> 
> Until such time as a community structure is put in place to maintain this site, it will be maintained as required by the tools team, Temporary RFC Series Project Manager, LLC and RPC.  The content is all available on GitHub [9] and issues and pull requests are welcome.
> 
> 
> # Outstanding work
> 
> There is some work that will be completed after community review:
> 
> - Adding MIB/YANG specific XML templates
> - Adding more examples to the vocabulary reference
> 
> 
> # Go live
> 
> The plan is for the site to go live when the big switchover from tools.ietf.org happens (that includes more than just this site).  The front page of tools.ietf.org and possibly it's 404 page will then redirect to this site. In addition, the following needs to happen to ensure that we do not continue with multiple sets of duplicate and inconsistent documentation:
> 
> - the RPC will review the content on the rfc-editor.org site and remove/redirect/refresh as appropriate 
> - xml2rfc will not longer output details of the vocabulary but refer instead to this site
> - the IESG will decide what to do about the Guidelines for I-D Authors 
> 
> 
> # Community review
> 
> Please let us know what you think of this site and if you have any specific issues or suggestions then a GitHub issue or pull request at https://github.com/ietf-authors/authors.ietf.org would be ideal.  It expected that this will be an ongoing process of review and improvement.
> 
> Jay
> 
> [0]  https://tools.ietf.org
> [1]  https://xml2rfc.tools.ietf.org/xml2rfc-doc.html
> [2]  https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html
> [3]  https://www.rfc-editor.org/rse/wiki/doku.php?id=svg_files
> [4]  https://www.rfc-editor.org/rse/wiki/doku.php?id=v3_feature_usage
> [5]  https://www.ietf.org/standards/ids/guidelines/
> [6]  https://authors.ietf.org/en/templates-and-schemas
> [7]  https://github.com/ietf-authors/rfcxml-templates-and-schemas 
> [8]  https://github.com/ietf-authors/legacy-templates-and-schemas
> [9]  https://github.com/ietf-authors/authors.ietf.org
> 
> —— 
> 
> -- 
> Jay Daley
> IETF Executive Director
> exec-director@ietf.org

-- 
---
tte@cs.fau.de