Hi
Behcet,
In-line with <bhs> ... </bhs>
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?
<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.
Barbara
|
