Subject: [Tools-discuss] Outstanding updates to authors.ietf.org now complete.

From: Jay Daley <[email-masked]>
Date: Thu, 24 Feb 2022 15:47:36 +1300

There were a few outstanding updates required to the authors.ietf.org site that have now been made:

1.  The inclusion of a Quick Start Guide.  This is at the front of https://authors.ietf.org/en/getting-started and reflects the text discussed on the emo-dir list.  The reference to the GitHub I-D template template is a bit clumsy and could be tidied up. (Also, I am of the view that is too complex for a quick start guide, but in the rough on that one).

2.  An explanation of the standard character entities and examples of their usage as provided by the RPC  https://authors.ietf.org/en/templates-and-schemas#character-entities

3.  In the RFCXML vocabulary, removing references to the RSE and/or lists maintained by the RSE that never existed.

Some minor tidying up is needed to reflect the renaming of kramdown-rfc but that’s now pretty much normal maintenance.

Jay

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

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 24 Feb 2022 03:52:33 +0100

On 2022-02-24, at 03:47, Jay Daley <[email-masked]> wrote:
> 
>  https://authors.ietf.org/en/templates-and-schemas#character-entities

Why doesn’t this point to the other markdown skeletons?
(What this page calls “templates”…)

Markdown doesn’t have the concept of a schema, so the “yet” is confusing.

Grüße, Carsten

---

From: Jay Daley <[email-masked]>
Date: Thu, 24 Feb 2022 16:39:27 +1300

> On 24/02/2022, at 3:52 PM, Carsten Bormann <[email-masked]> wrote:
> 

If you let me know what other ones it should point to then I will add them.
> Markdown doesn’t have the concept of a schema, so the “yet” is confusing.

Yeah, wishful thinking.

Jay

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

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 24 Feb 2022 04:44:13 +0100

> If you let me know what other ones it should point to then I will add them.

Maybe we can make life easier by pointing to just one more skeleton:

https://github.com/cabo/kramdown-rfc/blob/master/examples/draft-rfcxml-general-template-standard-00.xml-edited.md

Of course, the YAML header looks awful in github’s default rendering, so maybe:

https://raw.githubusercontent.com/cabo/kramdown-rfc/master/examples/draft-rfcxml-general-template-standard-00.xml-edited.md

I’m sure this semi-cadillac skeleton needs some more work, but it already shows most of what is needed for a draft today.  I probably should put out rendered versions of that skeleton as well...

Grüße, Carsten

---

From: Lars Eggert <[email-masked]>
Date: Thu, 24 Feb 2022 09:22:21 +0200

Hi,

>> https://authors.ietf.org/en/templates-and-schemas#character-entities

this is probably a larger ask, but I think it would make sense to split this wiki more thoroughly in a "drafting in Markdown" and "drafting in XML" branches.

This is already somewhat there by having left-menu pages with those titles (I'd order Markdown first, however).

But then the page a the URL above (and possibly) others mix XML and Markdown content on one page, which makes them look busy and makes them carry content that is irrelevant for authors using the other toolchain.

Thanks,
Lars

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 24 Feb 2022 07:28:44 -0800

On 23 Feb 2022, at 23:22, Lars Eggert wrote:

> this is probably a larger ask, but I think it would make sense to 
> split this wiki more thoroughly in a "drafting in Markdown" and 
> "drafting in XML" branches.

+1. As someone who helps near-novice draft authors who don't understand 
either Markdown or XML, I can assure you that the more we make those 
separate, the better it will be for the folks we are trying to help in 
our community.

--Paul Hoffman

---

From: Bob Hinden <[email-masked]>
Date: Thu, 24 Feb 2022 08:31:46 -0800

Paul,

> On Feb 24, 2022, at 7:28 AM, Paul Hoffman <[email-masked]> wrote:
> 
> +1. As someone who helps near-novice draft authors who don't understand either Markdown or XML, I can assure you that the more we make those separate, the better it will be for the folks we are trying to help in our community.

I agree.   That would even make it more useful for me:-)

Bob

> 
> --Paul Hoffman
> 
> ___________________________________________________________
> 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: Jay Daley <[email-masked]>
Date: Fri, 25 Feb 2022 09:59:19 +1300

> On 24/02/2022, at 8:22 PM, Lars Eggert <[email-masked]> wrote:
> 
> Hi,
> 

This templates page is pretty much the only page that can neatly be split into two pages, one for RFCXML and one for Markdown.  Apart from those that are already RFCXML specific, the rest of the pages are all task oriented and their content cannot be practically split into two (that’s also a bad idea from a usability perspective).

So we could split this template page and have a Markdown section of the menu, but for now it is going to a lonely section with just one page in it with barely five lines of text, which is something I’ve been trying to avoid based on previous feedback about not having short pages.  However, if we think the  Markdown-specific section will grow over time then it’s best to do that now and fix up all the links before they get embedded in lots of other sites.

Thoughts?

Jay

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

---

From: Jay Daley <[email-masked]>
Date: Tue, 1 Mar 2022 17:06:58 +1300

Following up on this.  I haven’t split out that templates page but after a number of offlist discussions, I have changed the flow and added some more content that should support people who just want to get on with it quickly and to nudge them to Markdown unless all the pre-conditions are met for a good XML experience.

Jay

> On 25/02/2022, at 9:59 AM, Jay Daley <[email-masked]> wrote:
> 
> Signed PGP part
> 
> 
> [email-masked] <mailto:[email-masked]>
> 
> 
> 

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