Hi Barbara,
On Fri, Feb 26, 2021 at 1:11 PM STARK, BARBARA H <bs7652@xxxxxxx> 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
