Subject: Re: [Emo-dir] quick-start guides

From: Carsten Bormann <[email-masked]>
Date: Tue, 1 Feb 2022 09:44:14 +0100

On 1. Feb 2022, at 04:29, Jay Daley <[email-masked]> wrote:
> 
> The standard term used by the tools team is "rendering".  This predates me so I don’t the know origins but authors.ietf.org uses this term and "converting" where "rendering" would be hard to understand.  I agree that it has a one-time implication but some times we just need to pick a word.

Yes, and I was pointing out that the one that was picked maybe isn’t so good after all.
Greg Wood came up with “processing”, which would be my recommendation.

Grüße, Carsten

---

From: "Salz, Rich" <[email-masked]>
Date: Tue, 1 Feb 2022 15:31:17 +0000

>     1. As below, do we recommend Markdown over XML or let people choose?  The authors site currently lets people choose but that can change.

At the EMODIR call last week, Alice said that statistics show 90% is XML and under 10% is markdown, with a smattering of other things.

So let's pick the top two for now, xml and kramdown.

---

From: Wes Hardaker <[email-masked]>
Date: Tue, 01 Feb 2022 09:23:58 -0800

"Salz, Rich" <rsalz=[email-masked]> writes:

> > 1. As below, do we recommend Markdown over XML or let people choose?
> The authors site currently lets people choose but that can change.
> 
> At the EMODIR call last week, Alice said that statistics show 90% is
> XML and under 10% is markdown, with a smattering of other things.
> 

We should pick ones that we think will be the easiest to get people
started producing stuff, regardless of what the current crowd is using
(because they've been using XML for so long I'm sure it's the most
popular).

To help people they need:
1. an easy to use/edit language
2. an easy to use build tool
3. documentation
4. A list of alternatives to 1 and 2 if they wish to explore

What the right answers are to 1 and 2 I'm not sure.  To *me*, markdown
is far easier for people to understand and get started with because it's
syntax is probably already understood by new folks.  I can still never
remember the right XML tag for a list, etc, and whether or not it should
be nested inside a <t>, etc.  One downside of the markdown format(s) is
that it's unclear how to do the extra required stuff (wg name, ipr
statements, etc) without a clear template to start with because we
require so much extra metadata.  Once I got my own template to copy each
time, life became much easier.  But I probably wrote 2-3 drafts in xml
that I wanted to do in markdown but couldn't figure out how to get
started quickly and didn't spend the time until later to figure out all
the right magic syntax in markdown.  And there's the rub: both formats
require some magic syntax.

I think MT's build environment is great, except that I actually don't
understand much of it when I glance at it the first time.  It's an
overwhelming makefile and needs a better getting started guide (IMHO; no
offense intended -- it could have just been me and my minimal brain).
So for *me* I actually forked my own copy of a simplified version that I
use as a template because my minimal brain understands it better.

-- 
Wes Hardaker
USC/ISI

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 1 Feb 2022 18:56:50 +0100

> At the EMODIR call last week, Alice said that statistics show 90% is XML and under 10% is markdown, with a smattering of other things.

I don’t know about 90 % of what, but here’s my statistics of the last 300 days of I-D submissions:

$ find ~/std/id/ -name \*.xml -mtime -300 | wc
    3213    3213  189521
$ find ~/std/id/ -name \*.xml -mtime -300 | xargs grep -l kramdown | wc
     925     925   53698

More like: 29 % of the I-Ds submitted as XML show that they are kramdown-generated.

This simplistic method doesn’t see the drafts that are still being submitted as text (some of which are generated by kramdown-rfc, but then there is Word, nroff, …).  It also counts submissions (revisions), not distinct drafts.
But it is still a useful indicator (*).

Grüße, Carsten

(*) “The future is already here – it's just not evenly distributed.”
― William Gibson

---

From: Mirja Kuehlewind <[email-masked]>
Date: Tue, 1 Feb 2022 19:02:27 +0100

I believe her numbers were on publish RFCs, not Internet-Drafts, and the assumption was already that the number is higher (and likely) increasing for drafts. Thanks for providing this number!

However, for the quick start guide for me the more important questions is what find people easier to use when they are starting as newcomers in the IETF for their very first (and in some cases even only) draft. For sure people likely don’t start by installing software on their device, so what they need is an actual template file, a (text) editor, and an online tool for conversion. 

Mirja

> On 1. Feb 2022, at 18:56, Carsten Bormann <[email-masked]> wrote:
> 
> _______________________________________________
> Emo-dir mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/emo-dir

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 1 Feb 2022 20:41:52 +0100

> I believe her numbers were on publish RFCs, not Internet-Drafts, and the assumption was already that the number is higher (and likely) increasing for drafts. Thanks for providing this number!

Then I’m not sure what that number expresses.
I write all my IETF documents in kramdown-rfc.
I never give anything but the generated XML to the RFC editor (well, they could extract the markdown if they wanted to, but I know that their processes center around XML).
Am I in the 10 % or the 90 %?

I think the draft submission percentage indicates where people do their authoring work.

> However, for the quick start guide for me the more important questions is what find people easier to use when they are starting as newcomers in the IETF for their very first (and in some cases even…

I’m not sure newness in the IETF correlates with the level of affinity to software production techniques.
There will be IETF newbs who will be put off by an environment that favors pure Web tools over locally installable tools that are amenable to source control, Makefiles etc.
(And, conversely, there are old hands who like Web tools a lot.)

The only thing that is true over the IETF as a whole is that different pockets are different.
So, as I’d recommend in general, design for choice.
(But not unreasonable levels of choice.)

Grüße, Carsten

---

From: Jay Daley <[email-masked]>
Date: Wed, 2 Feb 2022 08:53:14 +1300

> On 2/02/2022, at 6:23 AM, Wes Hardaker <[email-masked]> wrote:
> 

The importance of templates is something we appear to have consistently underestimated, which I hope is now fixed for XML.  As part of the authors.ietf.org site we have three new templates

	https://authors.ietf.org/en/templates-and-schemas

The advantages these have over the previous template(s) are

- they suit all levels of knowledge, from the bare bones version for experts to the one with comprehensive examples for beginners
- they are correct in the way they use RFCXML (e.g. they use <sourcecode> for source code not <artwork>)
- they follow the RPC’s best practice (e.g. they use xi:include for references)
- they support modern XML tools that provide syntax-aware editing
- they don’t have any unnecessary external dependencies
- they are on GitHub and open to community change requests

It would be good if we could do the same for the Markdown variants.

Jay

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

---

From: Mirja Kuehlewind <[email-masked]>
Date: Tue, 1 Feb 2022 21:03:06 +0100

Not disagreeing with your point but the problem we discussed that the last meeting is that there is currently just too much choice and we need a quick start guide for those who actually just want A (simple) way to submit a draft….

> On 1. Feb 2022, at 20:41, Carsten Bormann <[email-masked]> wrote:
>

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 1 Feb 2022 21:35:06 +0100

> Not disagreeing with your point but the problem we discussed that the last meeting is that there is currently just too much choice and we need a quick start guide for those who actually just want A…

OK, so let me try to summarize my point in an actionable way:

Pointing to just one X: too little choice
Pointing to XML authoring and kramdown-rfc authoring: right level of choice
Pointing to the whole smörgåsbord: too much choice

(But links to the smörgåsbord should be actively collected.)

Grüße, Carsten

---

From: Toerless Eckert <[email-masked]>
Date: Wed, 2 Feb 2022 05:25:59 +0100

> However, for the quick start guide for me the more important questions is what find people easier to use when they are starting as newcomers in the IETF for their very first (and in some cases even…

I would add a reasonable simple number of local install options for xml2rfc and kramdown-rfc2629
to the list. In my experience user satisfaction and productivity goes up when not having to
use the web version of the tools. And xml2rfc and kramdown-rfc2629 are installable
with few lines of CLI on most systems.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: Karen O'Donoghue <[email-masked]>
Date: Wed, 2 Feb 2022 14:32:15 +0000

I strongly agree with Mirja here. The problem we were discussing last week was how to help people get started... quickly... without overwhelming them with options and choices. I think we need a very limited set of choices in this instance. At the end of the short quick start guides... we can point to more information and detailed instructions elsewhere.

Remember this can always evolve as we learn more. Done is better than perfect.

Karen
________________________________
From: Emo-dir <[email-masked]> on behalf of Mirja Kuehlewind <[email-masked]>
Sent: Tuesday, February 1, 2022 3:03 PM
To: Carsten Bormann <[email-masked]>
Cc: Salz, Rich <[email-masked]>; Lars Eggert <[email-masked]>; Alice Russo <[email-masked]>; Jay Daley <[email-masked]>; [email-masked] <[email-masked]>
Subject: Re: [Emo-dir] quick-start guides

---

From: Andrew Campling <[email-masked]>
Date: Wed, 2 Feb 2022 16:57:08 +0000

> Remember this can always evolve as we learn more. Done is better than perfect.

I agree that the emphasis should be on simplicity, although I can see the temptation to offer multiple options given there are different types of new authors that may benefit from this guidance.  To simplify things, it may be useful to have something like:

"Software developers familiar with GitHub should start here ... (a single path with as few steps as possible to get to draft submission)

Technical authors with experience of markdown should start here ...

Technical authors familiar with XML should start here ... "

Etc

No doubt agreement on appropriate labels for the various categories will need discussion, the idea would be to point to a single path for each one from start to finish, potentially signposting additional material at the end such as more sophisticated templates and tools for those that aspire to more advanced documents.  NB I think that we should be cautious with paths that are dependent on tools being loaded onto devices as this may present a problem for some enterprise policies, although this should be fine as part of a list of additional material and tools.

We are still missing something suited to less sophisticated potential authors that may nevertheless be able to offer valuable contributions including, for example, those from civil society, industry bodies and other groups of end-users not versed in the use of GitHub, Markdown etc.  The current options are still likely to be perceived as a significant barrier to entry for some compared to, for example, a step-by-step guide to producing an I-D using Word.  Others may disagree but I firmly believe it is important to make it possible for such groups to participate if the IETF is to diversify the membership beyond the tech and telecoms sectors.

Andrew

---

From: Toerless Eckert <[email-masked]>
Date: Wed, 2 Feb 2022 19:13:47 +0100

I think the first target is authors familiar with nothing writing new draft.
  -> kramdown over the web

Second target is IMHO technical authors familiar with nothing joining an existing XML draft.
  -> XML over the web.

Third target is technical authors that need to be able to work offline
  (planes, trains, offices (with bad firewalls), beaches, etc. pp).
  -> local install of kramdown, xml2rfc - and i fear references libraries.

Everything else is IMHO below the first success goal line
(but then i am intentionally thinking someone who can already do github can
 help herself a lot more than above audiences...)

Cheers
    Toerless

-- 
---
[email-masked]