Subject: Re: document writing/editing tools used by IETF

From: Behcet Sarikaya <[email-masked]>
Date: Mon, 1 Mar 2021 09:56:28 -0600

Hi Barbara,

On Fri, Feb 26, 2021 at 1:11 PM STARK, BARBARA H <[email-masked]> wrote:

> As someone who has used just about all of the front-end tools mentioned in
> this thread (with front-end, I'm excluding all the processing tools because
> I've only used a few of those), I'd like to say that I really enjoy
> collaborative editing of markdown in GitHub and find it to be an excellent
> tool that is fully accessible to anyone with an Internet connection and a
> browser. I recently finished a document with a bunch of
> people-who-do-not-write-code -- some of whom didn't even have a GH account
> before this. I provided instructions. The only people who had issues
> contributing were the ones who never tried. Everyone who read the
> instructions and tried had no problem. If I had to provide instructions to
> someone who had never used Word, I suspect it would be a lot harder. Not to
> mention the cost of a Word license. One of the things that became clear in
> this process is that some people think you need to be running git on a
> local machine; that's not true.
>
> If anyone is curious, these are the instructions I provided:
> ====================
> ## Signing up for a GitHub (GH) account
>
> Everyone needs a GitHub account to participate. To set up a GH account, go
> to https://github.com/ and enter a preferred username, the email address
> you want to associate with the account (personal or work, depending on
> preferences and your corporate policies), and a password.  GH will impose
> username uniqueness and password strength.
>
> ## Signing in to GH
>
> The https://github.com/ page defaults to "Sign Up". Click "Sign In" at
> the upper right to get the "Sign In" page if you already have an account.
>
> ## Using the GitHub UI
>
> In the [repository](https://github.com/ <account>/<repo>), click on the
> file you want to edit, and then click on the pencil icon in the upper right
> of the file. Do your edits. When done, scroll to the bottom of the page,
> **select the checkbox that says "Create a new branch for this commit and
> start a pull request"** (this is really important), and click on the
> "Propose Changes" button. If the button says "Commit Changes" instead of
> "Propose Changes", then you need to click the "Create a new branch for this
> commit and start a pull request" button first. On the next page that
> appears, click "Create pull request". If you think some description of your
> changes might help, feel free to enter something in the "Leave a comment"
> box (either for Propose Changes or the Pull Request).
>
> If you want to work on the Pull Request (PR) over time or provide
> additional edits to your existing PR, you can do this at any time before
> the PR is merged. To do this, you simply edit files in your newly created
> branch. Select your branch from the pulldown menu (default branch in the
> pulldown is "Main") at the upper left of the [<account>/<repo> Code](
> https://github.com/bitag-twg-org/bitag2.0) page. The pulldown menu is
> located right under the `<> Code` tab heading. After your PR is merged,
> that branch will be automatically deleted.
>
> ## Using Markdown
>
> ======================
> This last part of the instructions had a link to
> https://guides.github.com/features/mastering-markdown/.
> For an IETF draft that is going to be processed using kramdown-rfc2629, I
> would also include a link to https://github.com/cabo/kramdown-rfc2629.
> I haven't used mmark or Phil's tools.
> But I don't think the average author needs (or should need) to know much
> more than headers, paragraphs, lists, and IETF references. The first 3 are
> really, really simple. References aren't hard.
>
> And that's it. I think if we made GH draft authoring this simple for
> people in IETF, opposition to it would disappear.
> The main thing I think is missing is easy set up of GH workflows to create
> XML and HTML artifacts.
>
>
I never used GH like you mentioned above. I know that it is used in Quic WG
and possibly others. If I understand well, it is used to create a draft in
text format not in xml2rfc format,
isn't that a big negative?

I find the "I hate Word" vs "I hate GH" argument to be futile. Just make it
> this easy for everyone to use GH and there'd be no argument.
>
>
agreed

Behcet

> Barbara

---

From: "Salz, Rich" <[email-masked]>
Date: Mon, 1 Mar 2021 17:56:32 +0000

*   I never used GH like you mentioned above. I know that it is used in Quic WG and possibly others. If I understand well, it is used to create a draft in text format not in xml2rfc format,  isn't that a big negative?

QUIC, HTTP-BIS, HTTPAPI, TLS are among the groups using GitHub for drafts.  You should check it out :)

Drafts seems to usually be written in a markdown known as kramdown, and there is tooling to do kramdown->xml, and then checking, formatting, etc., and even submission of the XML to datatracker.  So, no negative.  Lots of automation thanks to https://github.com/martinthomson/i-d-template

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Mon, 1 Mar 2021 17:59:03 +0000

Hi Behcet,
In-line with <bhs> ... </bhs>
Barbara

On Fri, Feb 26, 2021 at 1:11 PM STARK, BARBARA H <[email-masked]<mailto:[email-masked]>> wrote:
As someone who has used just about all of the front-end tools mentioned in this thread (with front-end, I'm excluding all the processing tools because I've only used a few of those), I'd like to say that I really enjoy collaborative editing of markdown in GitHub and find it to be an excellent tool that is fully accessible to anyone with an Internet connection and a browser. I recently finished a document with a bunch of people-who-do-not-write-code -- some of whom didn't even have a GH account before this. I provided instructions. The only people who had issues contributing were the ones who never tried. Everyone who read the instructions and tried had no problem. If I had to provide instructions to someone who had never used Word, I suspect it would be a lot harder. Not to mention the cost of a Word license. One of the things that became clear in this process is that some people think you need to be running git on a local machine; that's not true.

Everyone needs a GitHub account to participate. To set up a GH account, go to https://github.com/<https://urldefense.com/v3/__https:/github.com/__;!!BhdT!zkohVasj9JUs4K4NfFlMWyyKMH-0SJXKhxuetOKw8-CIBhKopg-Z8u9DG8MlVA$> and enter a preferred username, the email address you want to associate with the account (personal or work, depending on preferences and your corporate policies), and a password.  GH will impose username uniqueness and password strength.

## Signing in to GH

The https://github.com/<https://urldefense.com/v3/__https:/github.com/__;!!BhdT!zkohVasj9JUs4K4NfFlMWyyKMH-0SJXKhxuetOKw8-CIBhKopg-Z8u9DG8MlVA$> page defaults to "Sign Up". Click "Sign In" at the upper right to get the "Sign In" page if you already have an account.

## Using the GitHub UI

In the [repository](https://github.com/<https://urldefense.com/v3/__https:/github.com/__;!!BhdT!zkohVasj9JUs4K4NfFlMWyyKMH-0SJXKhxuetOKw8-CIBhKopg-Z8u9DG8MlVA$> <account>/<repo>), click on the file you want to edit, and then click on the pencil icon in the upper right of the file. Do your edits. When done, scroll to the bottom of the page, **select the checkbox that says "Create a new branch for this commit and start a pull request"** (this is really important), and click on the "Propose Changes" button. If the button says "Commit Changes" instead of "Propose Changes", then you need to click the "Create a new branch for this commit and start a pull request" button first. On the next page that appears, click "Create pull request". If you think some description of your changes might help, feel free to enter something in the "Leave a comment" box (either for Propose Changes or the Pull Request).

If you want to work on the Pull Request (PR) over time or provide additional edits to your existing PR, you can do this at any time before the PR is merged. To do this, you simply edit files in your newly created branch. Select your branch from the pulldown menu (default branch in the pulldown is "Main") at the upper left of the [<account>/<repo> Code](https://github.com/bitag-twg-org/bitag2.0<https://urldefense.com/v3/__https:/github.com/bitag-twg-org/bitag2.0__;!!BhdT!zkohVasj9JUs4K4NfFlMWyyKMH-0SJXKhxuetOKw8-CIBhKopg-Z8u-Pyg8_Xw$>) page. The pulldown menu is located right under the `<> Code` tab heading. After your PR is merged, that branch will be automatically deleted.

## Using Markdown

======================
This last part of the instructions had a link to https://guides.github.com/features/mastering-markdown/<https://urldefense.com/v3/__https:/guides.github.com/features/mastering-markdown/__;!!BhdT!zkohVasj9JUs4K4NfFlMWyyKMH-0SJXKhxuetOKw8-CIBhKopg-Z8u91-Z02qA$>.
For an IETF draft that is going to be processed using kramdown-rfc2629, I would also include a link to https://github.com/cabo/kramdown-rfc2629<https://urldefense.com/v3/__https:/github.com/cabo/kramdown-rfc2629__;!!BhdT!zkohVasj9JUs4K4NfFlMWyyKMH-0SJXKhxuetOKw8-CIBhKopg-Z8u_Zb4dr_Q$>.
I haven't used mmark or Phil's tools.
But I don't think the average author needs (or should need) to know much more than headers, paragraphs, lists, and IETF references. The first 3 are really, really simple. References aren't hard.

And that's it. I think if we made GH draft authoring this simple for people in IETF, opposition to it would disappear.
The main thing I think is missing is easy set up of GH workflows to create XML and HTML artifacts.

I never used GH like you mentioned above. I know that it is used in Quic WG and possibly others. If I understand well, it is used to create a draft in text format not in xml2rfc format,
isn't that a big negative?

<bhs> Some drafts are edited in GH as XML. This is especially true of YANG drafts, AFAICT. But many have gone to using markdown and then use either kramdown-rfc2629 or mmark to generate IETF xml. The instructions for getting a GH account, signing into GH, and using the GH UI are independent of whether the file being edited is kramdown markdown, mmark markdown, or IETF xml. These are all edited in GH in their native un-rendered text-based form. Since un-rendered markdown is really simple to edit and read (simpler than un-rendered XML), using markdown is simpler for someone who has little or no familiarity with XML or markdown (or Word). The negative I’ve experienced is that running the XML-generating tools is sufficiently complex (at this time) that this activity isn’t for everyone. But it’s not necessary for people who contribute text to have to do the conversion. It can be the WG chair or just one of the authors who runs conversion tools when it’s time to generate a draft revision. Or to set up / use Martin Thomson’s i-d-template tool. But using or automating Martin’s tool isn’t for the novice. BTW, this is also true of YANG drafts that have special tools to combine the YANG source with text parts of a draft (and auto-generate the parameter tree). I’m a co-author on a YANG draft where I find using the generating tools to be complicated (to remember how to do this without a cheat sheet because I do it rarely) so I leave generating the single IETF xml file to the lead author. </bhs>

I find the "I hate Word" vs "I hate GH" argument to be futile. Just make it this easy for everyone to use GH and there'd be no argument.

agreed

Behcet

Barbara

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Tue, 2 Mar 2021 17:21:13 -0500

On Sun, Feb 28, 2021 at 10:38 PM John Wroclawski <[email-masked]> wrote:

>
>
> > On Feb 25, 2021, at 4:21 PM, Brian E Carpenter <
> [email-masked]> wrote:
> >>> Good point about publications. RFCs are publications, too, so there is
> definitely some ROI in (co-)authoring an RFC as an academic. However,
> usually the entire process takes much longer than writing academic papers.
> And I'm not sure how academia at large values RFCs relative to papers, but
> at least in the part that I know, I would say they're valued.
> >>
> >> One thing we did to increase the value of RFCs to academics was to
> assign them DOIs, which at least for universities in some geos is a
> prerequisite to even recognizing RFCs as academic output.
> >
> > Nevertheless, it is in general hard to get RFCs recognised as valuable
> for tenure and promotion purposes, compared to more traditional publication
> streams such as highly-rated journals. That's one reason we did
> https://dl.acm.org/doi/10.1145/1672308.1672315 but I'm not sure it has
> had much impact.
>
> Seconding Brian’s comment (and Keith’s in the next msg), the DOI effort
> and CCR articles were excellent, necessary first steps, but by themselves
> they’re not likely to change the landscape very much, I think.
>
> The issue is more fundamental. Academia wishes to claim that its highest
> value publications are “original research”, and consensus-driven standards
> with the stated goal of codifying existing or emerging practice don’t
> “look” like that. My weasel words are because both sides of this stereotype
> are sometimes truly true and sometimes, well, not. But it's the perception,
> and it’ll be really hard to get the academic publication world to weigh
> RFCs heavily without changing it in some way.
>
> Which, I think, might possibly be doable. Academia does have other values
> - you can get brownie points for a good survey paper, for example, because
> you’re "systematizing knowledge" - and increasingly (although not as much
> as one might hope) work that validates research results by showing the
> they’re repeatable is seen as publishable. But the trick here is to frame
> this as a case that RFCs and IETF participation advance some substantive
> academic value - not just to argue that they follow the “form” of academic
> publication by being peer-reviewed and having DOIs. I’m not sure if
> anyone’s every quite tried to do this, but it seems at least potentially
> possible.
>

+1

I have the profound luxury of not needing to play the academic game for
either recognition or for research funding. As far as I am aware, I am the
only person currently working on TKI. I don't expect that to change soon.

The way to fix Academia is to look at the funding structures that support
it. MIT tenure committees don't look at the number of publications in
academic journals because they think them a good way to assess the
intellectual calibre of a candidate. They use them because that is the
yardstick they know that DARPA, NSF, etc use. And they use them because
they can't currently think of a better one.

So the way to fix the problem is to fix Academia. Which is something that
might well take half a century or more to fully realize. But a start is
being made.

The UK recently made a requirement that all government funded research has
to be published in journals that are open access. While discussing this
with one of the politicians behind the move I pointed out that they were
going to be facing opposition from UK academics who were likely to find it
harder to get positions at prestigious overseas universities. Turned out
that was a feature, not a bug.
If we had a digital environment that allowed a better understanding of the
intellectual contributions being made by individual academics than
publications in academic journals, there would be a lot of interest from
all the stakeholders.

---

From: Wes Hardaker <[email-masked]>
Date: Fri, 05 Mar 2021 06:12:44 -0800

Phillip Hallam-Baker <[email-masked]> writes:

> The way to fix Academia is to look at the funding structures that support it.
...
> So the way to fix the problem is to fix Academia.

You highlight the problem well that there are multiple confounding
issues that all mingle together.

(Most) RFCs are typically harder to get published than academic
papers.  They take multiple years to get published and require extensive
negotiations with many parties.  This leads to:

1) Its not really a viable goal for students to take on, since they're
likely to graduate before the completion of the publication effort.  Nor
can you ensure consensus, and isn't easy "fallback publication venues" if
you fail the IETF as the tier-1 to publish in.

2) That leaves staff and faculty to do the work, which means funding
agencies must understand both the long term commitment required (2-3
years beyond the point of the solution being initially documented) and
the cost required (its not the travel cost -- its the labor required for
said negotiations).  Then there is the "running code" cost, that will
likely keep changing as the eventually-to-be-standard keeps changing
underneath the code.

When I've discussed contracting with funding sources before for research
work, and explained situation #2 I've often given them two quotes: one
just to do the work and a second that included a standardization-effort
cost that wasn't even assured.  Many organizations saw the second and
understandably didn't take that option.

And then, yes, you're right that academia must change as well.  Back in
early days the IETF was seen as a place to do research.  Now its seen as
a place to do "real stuff" and many opinions exist that its "not
researchy enough to warrant our participation".

So, yes, I agree: both funding and academia itself needs to change in
order to bring them back in full force (we have light participation now,
but nothing like we had in the past).  The IRTF has greatly helped
improve things lately, IMHO and fortunately.

-- 
Wes Hardaker
USC/ISI