Subject: [Tools-discuss] authors.ietf.org now ready for community review

From: Jay Daley <[email-masked]>
Date: Fri, 17 Dec 2021 16:50:35 +1300

# 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
[email-masked]

---

From: Michael Richardson <[email-masked]>
Date: Fri, 17 Dec 2021 16:50:42 -0500

Jay Daley <[email-masked]> wrote:
    > 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 layout is so bad (two left-hand bars) that I really can't see past that
to the content.  Sorry to be so critical here.

    > novices, occasional authors and experts.
    
As a seasoned person, I can't really find anything relevant, because it seems
to be aimed at newbies.

I think, as a newbie, I'd be overwhelmed by the number of links I think that
I might care about, and I'd decide not to bother. The IETF is too hard.

    > - Documentation on the AUTH48 review and subsequent publication process
    > as those are processes for RFCs not I-Ds.  This remains on
    > rfc-editor.org

Yes, there is a diagram that sure looks like it contains details of the
process.

-- 
]               Never tell me the odds!                 | ipv6 mesh networks [ 
]   Michael Richardson, Sandelman Software Works        | network architect  [ 
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [

---

From: Eric Rescorla <[email-masked]>
Date: Fri, 17 Dec 2021 14:13:50 -0800

I share some of MCR's concerns here.

I think the underlying problem is that this feels like a reference
manual. Those of course have their place, but what's really needed is
an opinionated quickstart guide that tells people how to make
progress.

As a concrete example, when I go to "Drafting in XML" it tells me a
bunch of stuff about how to edit the document, but I need to go to
"Rendering and Converting" to learn how to actually make the document.
IMO a better approach would be a step-by-step guide to (for instance)
use markdown.

It would go like this.

1. First clone internet-draft-template
2. Rename your draft
3. Setup the repository with make setup (or whatever)
4. Now build the draft
5. Submit (e.g., using
https://github.com/martinthomson/i-d-template/blob/main/doc/SUBMITTING.md#github-release
)

As an example of what I'm talking about, here's the tutorial for
ExpressJS, which starts from nothing, goes through Hello World,
etc.

https://expressjs.com/en/starter/installing.html

Once people have the basics, we can teach them what Emacs plugin
to use with XML or whatever....

-Ekr

On Fri, Dec 17, 2021 at 1:50 PM Michael Richardson <[email-masked]>
wrote:

> ___________________________________________________________
> Tools-discuss mailing list - [email-masked]
> This list is for discussion, not for action requests or bug reports.
> * Report datatracker and mailarchive bugs to: [email-masked]
> * Report tools.ietf.org bugs to: [email-masked]
> * Report all other bugs or issues to: [email-masked]
> List info (including how to Unsubscribe):
> https://www.ietf.org/mailman/listinfo/tools-discuss
>

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 18 Dec 2021 11:14:57 +1300

Michael,

I've switched to https://author-tools.ietf.org/ as my goto page.
It has what I need and so far bugs and even feature requests are
fixed in about 24 hours.

So while you're correct that the info pages at authors.ietf.org
need more work, the feedback on them needs to come from genuine
newcomers, I think. That sounds like a job for EMO.

Also, how does a newcomer get from https://www.ietf.org/about/participate/get-started/ to author-tools? Also a question for EMO.

Regards
    Brian

On 18-Dec-21 10:50, Michael Richardson wrote:
> List info (including how to Unsubscribe): https://www.ietf.org/mailman/listinfo/tools-discuss
>

---

From: Jay Daley <[email-masked]>
Date: Sat, 18 Dec 2021 12:42:34 +1300

Thanks for the review - comments below. 

> On 18/12/2021, at 10:50 AM, Michael Richardson <[email-masked]> wrote:
> 
> 

There’s been a lot of feedback about this middle ‘page contents’ menu  in the initial testing, with some wanting it gone entirely, some wanting it moved to the right and some wanting it reimplemented in a different way. The next major release of the wiki product should address that. 
> As a seasoned person, I can't really find anything relevant, because it seems

It seems a bit of a bold claim that you know the full RFCXML vocabulary, the details of how to use all the tools and all the content guidelines. 
> I might care about, and I'd decide not to bother. The IETF is too hard.

The initial ‘release’ of this site reuses all of the existing content, which is all fairly detailed. We could certainly do with more content for newbies. 
> Yes, there is a diagram that sure looks like it contains details of the

Sorry that comment’s too cryptic for me to parse. 

Thanks again
Jay

-- 
Jay Daley 
IETF Executive Director
[email-masked]

---

From: Jay Daley <[email-masked]>
Date: Sat, 18 Dec 2021 12:46:35 +1300

> On 18/12/2021, at 11:14 AM, Eric Rescorla <[email-masked]> wrote:
> 
> 
> 5. Submit (e.g., using https://github.com/martinthomson/i-d-template/blob/main/doc/SUBMITTING.md#github-release)
> 

Thanks and I fully agree. The RPC have also suggested this. It’s straightforward to add. 

One question though is just how opinionated?  Do we provide one single one or one for XML and one for Markdown, one for with GitHub and one for without?

Thanks again
Jay

-- 
Jay Daley 
IETF Executive Director
[email-masked]
> 
>                 
> 
> 
> 
>> On Fri, Dec 17, 2021 at 1:50 PM Michael Richardson <[email-masked]> wrote:
>>

---

From: Eric Rescorla <[email-masked]>
Date: Fri, 17 Dec 2021 15:49:03 -0800

On Fri, Dec 17, 2021 at 3:46 PM Jay Daley <[email-masked]> wrote:

> One question though is just how opinionated?  Do we provide one single one
> or one for XML and one for Markdown, one for with GitHub and one for
> without?
>

I would think one with XML and one with Markdown and a separate one for how
to use MT's ID tools, which means Github.

-Ekr

---

From: Michael Richardson <[email-masked]>
Date: Sun, 19 Dec 2021 13:05:15 -0500

> to use MT's ID tools, which means Github.

I agree.  It should say something like:

"The IETF uses XML as the authoritative form for internet drafts and RFCs"
There are _many ways_ to generate the XML.
The recommended way for those who want to collaborate is with _kramdown_
format using _github.  The least effort is... <ekr opinioned version>"

---

From: Michael Richardson <[email-masked]>
Date: Sun, 19 Dec 2021 13:12:17 -0500

> It seems a bit of a bold claim that you know the full RFCXML
    > vocabulary, the details of how to use all the tools and all the content
    > guidelines.

Do I need to know the full RFCXML vocabulary? I'm certain I don't know it.
(I question if it is even knowable given the disconnect between xml2rfc code
and RFCs..., but that's a different discussion)

Do newbies need to know? I don't think so.

As a seasoned person I probably need search access to (open and closed) bug
reports on xml2rfc, so that I can determine if the problem that has taken me
to the site has already been reported/solved.
I probably want to search release notes as well.

    > The initial ‘release’ of this site reuses all of the existing content,
    > which is all fairly detailed. We could certainly do with more content
    > for newbies.

I think that the site needs to welcome newbies without distracting or
overwhelming them.   Right now, it overwhelms them, yet does nothing to
really help me.

    > Sorry that comment’s too cryptic for me to parse.

Here is a screen capture:
  http://www.sandelman.ca/tmp/mcrcapture/9376.2021-12-19/capture1.png

To a newbie, this looks like an overview of the RFC editing process,
as it ends with "RFC Publication".   Of course, those of us who know the
process know that this is just about the editing formats: there are no spots
here for WG Adoption, WGLC, IESG, AUTH48, etc.  But newbies won't know that.

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: "John Levine" <[email-masked]>
Date: 19 Dec 2021 15:21:07 -0500

It appears that Michael Richardson  <[email-masked]> said:
>-=-=-=-=-=-

The current grammar is a deep secret, known only to the elite few who have
typed

$ xml2rfc --docfile

and looked at the documentation, or who have looked at the github archive
of grammar files:

https://github.com/rfc-format/v3grammar

FYI, the grammar hasn't changed since xml2rfc 3.0 over a year ago.  I expect one
more minor update to clean up some loose ends.

I doubt that anyone knows the full grammar from memory.  Much of it is only
of occastional use.  We certainly don't need to throw it at new authors.

R's,
John