Re: authors.ietf.org now ready for review

[Jay Daley <[e-mail]>]

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
[e-mail]