Re: document writing/editing tools used by IETF

[Behcet Sarikaya <[e-mail]>]

Hi Barbara,


On Fri, Feb 26, 2021 at 1:11 PM STARK, BARBARA H <[e-mail]> 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
>
>
>