Re: document writing/editing tools used by IETF

Behcet Sarikaya <sarikaya2012@gmail.com> Mon, 01 March 2021 15:56 UTC

Return-Path: <sarikaya2012@gmail.com>
X-Original-To: ietf@ietfa.amsl.com
Delivered-To: ietf@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 5F46F3A1E86 for <ietf@ietfa.amsl.com>; Mon, 1 Mar 2021 07:56:44 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.847
X-Spam-Level:
X-Spam-Status: No, score=-1.847 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=gmail.com
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 4lgyagvY1u4N for <ietf@ietfa.amsl.com>; Mon, 1 Mar 2021 07:56:42 -0800 (PST)
Received: from mail-yb1-xb2d.google.com (mail-yb1-xb2d.google.com [IPv6:2607:f8b0:4864:20::b2d]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 44F6E3A1E68 for <ietf@ietf.org>; Mon, 1 Mar 2021 07:56:42 -0800 (PST)
Received: by mail-yb1-xb2d.google.com with SMTP id m9so17439611ybk.8 for <ietf@ietf.org>; Mon, 01 Mar 2021 07:56:42 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:reply-to:from:date:message-id :subject:to:cc; bh=zaoCFqgMAjd7b52vtS9hQs8IkxvYHGTmm6W6bu6PMiY=; b=MlamDQ/t9v9neWtaEHP1rFBjVf1xXP+5p243mFU9Ml035fFhm+a8LmVdNmW+CiMkWW fhWnLbKOWV95mxPLJaJ05gwyCWq80gdbMGMhr39u1Jgsw7rgbmcLZG4CYAzrjMlojYHC WKjdpNqp0QSZz0IyA9hKNtnvd4wfHowFykWJ1mXzfbsBAfDmYZyFkhIH1LrAXOloZ/jL fA4Hyr0Y2DLOEfnc2ltSC7JUanvykJdvVZyEewgK3aqcZ0jOcuJuqBXH0Sd1fpChkP13 CrYcJLmQhmLSI+7asx3MCNKCHD8MQxQHKwsQb/tw4pkQMDYuAd7zcejT9q+j3FbWvK1y zFyg==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:reply-to :from:date:message-id:subject:to:cc; bh=zaoCFqgMAjd7b52vtS9hQs8IkxvYHGTmm6W6bu6PMiY=; b=fMPVNdVa9/k1MkR/GZoWDDB9z21l8DL2nJdaF9EPaPsqmyrZN0mz8Egak92mFG8cl6 eukVl0LIo6NvXzZ3iNiNCNqbxU+p4Br+S0n1Ar61JjjGbqEq4bxVCEjH3i/EXaP+pTv9 227By69apU4UznA9lxxkSy9PEEVag43nQyG9sSVOIAHVk9FLaYeQAPojPH4Amu/iMX8p nPVqXSSjJ4cD3giMzcGfqeVfAbz2zLEQhDZ039ilpVRo3umHMIwreVzZj1HQo2HDPTY4 Rt+NrrLF0f9P1SeEREJSViKL0G4/sNoS69HlCC0YK0w0Q+5+CVYi35nntItma/7+Jvbu KNZQ==
X-Gm-Message-State: AOAM530uq3Npvp16jArAy0eZ8GZ3Z3CENJ0NQf1yj947rpQJxIIgnq+b FG4nNGrytFTE3dyROQVU61GLtlFktW6comM4yCY=
X-Google-Smtp-Source: ABdhPJylEQpjfGU3OilT0wt6NYv23FTymjWBEI4Uw6IZqhXuVlmyX6SC8Uu4ypc1cCYiG9Ii9wMl+9DN1O09jgrvFLs=
X-Received: by 2002:a25:ca42:: with SMTP id a63mr24406213ybg.318.1614614199624; Mon, 01 Mar 2021 07:56:39 -0800 (PST)
MIME-Version: 1.0
References: <37eecb9b-f0eb-e21c-b162-b1f0339e4981@si6networks.com> <3c2d646d-f18d-4d88-b458-29dbd486432b@beta.fastmail.com> <446A8D6B-E624-49E0-B67E-D1F8AFC794E2@lastpresslabel.com> <28ac1e86-f641-b9e8-0f61-6ff442feaa90@si6networks.com> <LO2P265MB057322BA95B1B44D4175356BC29E9@LO2P265MB0573.GBRP265.PROD.OUTLOOK.COM> <089096b1-10d2-3eac-d37c-f040a1930061@network-heretics.com> <37142313-C251-40DC-9336-D3A2F0FB69AD@tzi.org> <001d01d70be3$ff0972d0$fd1c5870$@acm.org> <CAMm+LwhkLTKkp3q4s97TBA-=WpJPof861mygPSjJttowpDjGuw@mail.gmail.com> <8b42a18a-181e-cad7-7333-3e950e643665@gmx.de> <C51C3823-59DA-4E61-B3A9-968BA355EEE2@depht.com> <DM6PR02MB692412D75E013F8EC314DAC6C39D9@DM6PR02MB6924.namprd02.prod.outlook.com>
In-Reply-To: <DM6PR02MB692412D75E013F8EC314DAC6C39D9@DM6PR02MB6924.namprd02.prod.outlook.com>
Reply-To: sarikaya@ieee.org
From: Behcet Sarikaya <sarikaya2012@gmail.com>
Date: Mon, 1 Mar 2021 09:56:28 -0600
Message-ID: <CAC8QAcc7=EN_4oTNQ0eKkbwkzCUmZcfm2K1JE2C5dKwHyYT9Qg@mail.gmail.com>
Subject: Re: document writing/editing tools used by IETF
To: "STARK, BARBARA H" <bs7652@att.com>
Cc: "ietf@ietf.org" <ietf@ietf.org>
Content-Type: multipart/alternative; boundary="000000000000d1685405bc7ba9bf"
Archived-At: <https://mailarchive.ietf.org/arch/msg/ietf/23Pq02iSLDnH5Psgs1jw1Ud7feg>
X-BeenThere: ietf@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: IETF-Discussion <ietf.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/ietf>, <mailto:ietf-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/ietf/>
List-Post: <mailto:ietf@ietf.org>
List-Help: <mailto:ietf-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/ietf>, <mailto:ietf-request@ietf.org?subject=subscribe>
X-List-Received-Date: Mon, 01 Mar 2021 15:56:44 -0000

Hi Barbara,


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