RE: document writing/editing tools used by IETF

"STARK, BARBARA H" <bs7652@att.com> Fri, 26 February 2021 19:11 UTC

Return-Path: <bs7652@att.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 85A593A0AD7 for <ietf@ietfa.amsl.com>; Fri, 26 Feb 2021 11:11:12 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.898
X-Spam-Level:
X-Spam-Status: No, score=-1.898 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=att.onmicrosoft.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 WHYxKqkNn7DP for <ietf@ietfa.amsl.com>; Fri, 26 Feb 2021 11:11:10 -0800 (PST)
Received: from mx0a-00191d01.pphosted.com (mx0b-00191d01.pphosted.com [67.231.157.136]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id C655D3A07BA for <ietf@ietf.org>; Fri, 26 Feb 2021 11:11:10 -0800 (PST)
Received: from pps.filterd (m0083689.ppops.net [127.0.0.1]) by m0083689.ppops.net-00191d01. (8.16.0.43/8.16.0.43) with SMTP id 11QJ4ncP016339 for <ietf@ietf.org>; Fri, 26 Feb 2021 14:11:09 -0500
Received: from alpi154.enaf.aldc.att.com (sbcsmtp6.sbc.com [144.160.229.23]) by m0083689.ppops.net-00191d01. with ESMTP id 36xg75dxdf-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT) for <ietf@ietf.org>; Fri, 26 Feb 2021 14:11:07 -0500
Received: from enaf.aldc.att.com (localhost [127.0.0.1]) by alpi154.enaf.aldc.att.com (8.14.5/8.14.5) with ESMTP id 11QJ6Ac9025370 for <ietf@ietf.org>; Fri, 26 Feb 2021 14:06:10 -0500
Received: from zlp30487.vci.att.com (zlp30487.vci.att.com [135.47.91.176]) by alpi154.enaf.aldc.att.com (8.14.5/8.14.5) with ESMTP id 11QJ67ls025323 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for <ietf@ietf.org>; Fri, 26 Feb 2021 14:06:07 -0500
Received: from zlp30487.vci.att.com (zlp30487.vci.att.com [127.0.0.1]) by zlp30487.vci.att.com (Service) with ESMTP id 352A64009E67 for <ietf@ietf.org>; Fri, 26 Feb 2021 19:06:07 +0000 (GMT)
Received: from GAALPA1MSGEX1BD.ITServices.sbc.com (unknown [135.50.89.105]) by zlp30487.vci.att.com (Service) with ESMTP id 17E7E4009E60 for <ietf@ietf.org>; Fri, 26 Feb 2021 19:06:07 +0000 (GMT)
Received: from GAALPA1MSGEX1DB.ITServices.sbc.com (135.50.89.115) by GAALPA1MSGEX1BD.ITServices.sbc.com (135.50.89.105) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2176.2; Fri, 26 Feb 2021 14:06:06 -0500
Received: from GAALPA1MSGETA01.tmg.ad.att.com (144.160.249.126) by GAALPA1MSGEX1DB.ITServices.sbc.com (135.50.89.115) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2176.2 via Frontend Transport; Fri, 26 Feb 2021 14:06:06 -0500
Received: from NAM12-MW2-obe.outbound.protection.outlook.com (104.47.66.48) by edgeal1.exch.att.com (144.160.249.126) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2176.2; Fri, 26 Feb 2021 14:05:47 -0500
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=g2ZckmvehEveXEWRXdZBdkssx+6w3i7QeaHYRbJr4Ey2TGviWhMTmjubA031iwfDGwyTJJJOQkDHHwdhcj6Eav6qdL6yCpxqBDww0sisrlBzNKQsP0+3V9+6MTcq8FOekCtA+fPnuKU+ambajVKi69m+7L4jsNhTxGBvXdS3KkxxliELIkdrbybvmNlhrCpIxyylNAjr/a/zYGKWKxXkfAQ9NpohIRdLHVQqxAcmapLU17fPxe1grM3DWrlfhGka+LTbsZ8apDgXhHKtzKYR4/cZAs1mGpCMUK144BXoUNkoMGPIRvkSfE16YfZ78W230t+wQsEBDt7im0O4yR99jQ==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=kpXGuZOiZZBZ1nlFLndBEZ+5403DpnWPtOnzalVT1XU=; b=HmOTmt0FmMI74siWjCTeDjShIgpRCg6lU4bquWHuBSwKq7o3xHjLefhd/SY+AH4UvLBEwk2em+sj8D8hWvyHP/kr9ADoE+Q23WOjUy5nW3KDLZBjUnNS7ghkXlm8PmcJTX4G/z5Wvtubem5MeYe5IJ74fKmQWa3expRCkPff169o4xN9eqrU3vrWa9NBBYx+jbUowHdneDRA15uvz2Gr+vV7EwGEr3n35aTGhhj2rndpN+YmqruwbBlCUzSJLxdxJq1Y+W96LXdASC0x1gchAqiz7FJVE8ePoqjash5Vr+TTFTidbX0eoxFWKpoHSfaPJo8ABttldCzLpGo0pf0cFQ==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=att.com; dmarc=pass action=none header.from=att.com; dkim=pass header.d=att.com; arc=none
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=att.onmicrosoft.com; s=selector2-att-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=kpXGuZOiZZBZ1nlFLndBEZ+5403DpnWPtOnzalVT1XU=; b=x5GeMFlaLQULUK2F5nQqEAVWX6oyroI/T/aBK/gg3oQnlux5DmMtaKn3zgC1oWUSUfcg/P6RDFqt8zkpK2H5udJT5KMFZWoH3EDUPHNSvye8UM6GXBknQNKBRN70nSoo1a/r6hCJIpLk7JxLn88RcwR3h6XIgiZJ1eyoZ0qeanY=
Received: from DM6PR02MB6924.namprd02.prod.outlook.com (2603:10b6:5:25f::7) by DM6PR02MB6922.namprd02.prod.outlook.com (2603:10b6:5:252::8) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3868.32; Fri, 26 Feb 2021 19:05:46 +0000
Received: from DM6PR02MB6924.namprd02.prod.outlook.com ([fe80::d9c0:4a62:170b:b925]) by DM6PR02MB6924.namprd02.prod.outlook.com ([fe80::d9c0:4a62:170b:b925%8]) with mapi id 15.20.3868.034; Fri, 26 Feb 2021 19:05:46 +0000
From: "STARK, BARBARA H" <bs7652@att.com>
To: "'ietf@ietf.org'" <ietf@ietf.org>
Subject: RE: document writing/editing tools used by IETF
Thread-Topic: document writing/editing tools used by IETF
Thread-Index: AQHXC7TODO9u7RfdDUynkIvzruTRCqppo2+AgAANIwCAABP/AIAATXwAgAA+QoCAAHUJwA==
Date: Fri, 26 Feb 2021 19:05:46 +0000
Message-ID: <DM6PR02MB692412D75E013F8EC314DAC6C39D9@DM6PR02MB6924.namprd02.prod.outlook.com>
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>
In-Reply-To: <C51C3823-59DA-4E61-B3A9-968BA355EEE2@depht.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
authentication-results: ietf.org; dkim=none (message not signed) header.d=none;ietf.org; dmarc=none action=none header.from=att.com;
x-originating-ip: [45.18.123.63]
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: 6364bcbb-f3d2-4092-3ccf-08d8da8985c5
x-ms-traffictypediagnostic: DM6PR02MB6922:
x-ms-exchange-minimumurldomainage: github.com#4889
x-microsoft-antispam-prvs: <DM6PR02MB6922A41FFE5EA9DEA0464A38C39D9@DM6PR02MB6922.namprd02.prod.outlook.com>
x-ms-oob-tlc-oobclassifiers: OLM:7691;
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info: rTyJvgECoos56G/tePccDHfnzWG7fEaN9+7XcwNZfeXuzVhQJdY1HiTO1U1eR4tyc/GVnwAM9ZzdTQd+6zAoEUmhXtX2HX9CSowKGRvAHjNWQFxhULo4aPE6b5qOBbo6FkVV7UYokzv1wDyN8aGBfcQfq+9iJWYJrbR9L0Waqv+YlsHIKVz/TEnjFRoeK5lWPVQz2vV/0030MnWEXEiOc9ShL7kmPcKaUzhRFBU3PXjoROHeTpbHZw3tcNk58ska9sHllKx9wr3Oix4cfW+vXUTTPBqSzyfxfGHU7tW+jAumtfVtl8KDOtJGnI7ZKKquZ2of+YvkidDzS9PiihiBingJxa0dyVgWvjMn+Dyv/Gk8TPsVKItdLu7sJFFq4+4v006zIg451AjiGseYkrjCfe95Ya4+i9j5mQdTn1IxMtqU8NiIMDCnRTnpoyhBAAXZ4IluG7TXCw2eC7v2i51pWKYpSQvyLrvtbK2nIKBnMQQZ4sGy5K2bWi95CPOHwy8M4gDiJUnuO/TXY37L+4Qyjtm5zqFXD47syd+As0Em5vA0ZIqvj9WDxC3Y12xuZaHj+FjCKCsJTgYk3FFKFhULTES88wwINgm8/kuynP5egBjYwSeXcA0w6MTbiteevsm3GppgRa1zhMMZ35FH+BUnpA==
x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DM6PR02MB6924.namprd02.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(346002)(39860400002)(376002)(136003)(366004)(396003)(66946007)(64756008)(82202003)(478600001)(5660300002)(66446008)(6506007)(66476007)(316002)(966005)(71200400001)(76116006)(2906002)(186003)(9686003)(26005)(6916009)(8936002)(66574015)(8676002)(86362001)(55016002)(83380400001)(66556008)(7696005)(33656002)(52536014)(491001); DIR:OUT; SFP:1101;
x-ms-exchange-antispam-messagedata: =?utf-8?B?YlNsT1JpM2NsRVgrRHl1SVBJUzlCaytXV3pGNTVwZGNXZXlBRDl1ajNETTZJ?= =?utf-8?B?WmluL1FzU3UrdnFwWWhaU3N3V0pYOGJ6S0xyY28wUHlqMU1ZUmpTVzJkVHEz?= =?utf-8?B?YlRBSmpPdUhGNUxBc0hoWWRXeE1tVE5oRUdHVk9nYUozYUN5SnNrcUxQKy8x?= =?utf-8?B?OHBzM21Yc0NIOVQrNFlyOHdoQlZpcjZOTVo3R2QwT1JXOTZheEpMODlBSXpN?= =?utf-8?B?TXdBSEtuTi81SXg3U1dYYUhEY0s1ZjhTYzZPcGF6OTlMVnU2eGxucjA4eHZC?= =?utf-8?B?WUllN3piRVB3RTZMNDRzVUIwajJvdVVoRUhaclNUUGhzVzBQVCtFZU5RRldR?= =?utf-8?B?RkpTalNQd1gvaE1rT1RuYStLMk13Q3NXczdBTk9qcnpmb2x3T3Nsd1RlWHA1?= =?utf-8?B?MkFRb3V3YXZzQmxLa1djQ2JXL1JVY2s1YXlKTGthbmUyNVNHZFB1OXc1OWpa?= =?utf-8?B?N0lnbmZVbmpBdmxTTjZ2U2c0dGEvczNJekkyQm9pK21adjZ3c2d3aTlWLzRN?= =?utf-8?B?M0VHN094WmNUemRYcVkzaDdKVzcyL3Blc2Rudzc5dm40YjNWYUFFTkdUSStB?= =?utf-8?B?aVpVTVBFYVRlVjB4QitNL1l4MEFtTnFDMGZnRFFSK2d6anN4MFJRVldFL2F6?= =?utf-8?B?ZlRremNnZUkyL3NpajZXN2Q3dWFmV0JRaXQ4VWNsR1JpeElHU29iQ2prQjdP?= =?utf-8?B?Skw0S3BLL1BkdXIzTFRocUtNSzd6YTZmODFJUjNFQ0Z0ak9EeTI5V3MrYU1N?= =?utf-8?B?aW1jdTJmMEliSUhmNDBSTHp4NktkcXhvR1FmalNVUjU5Q0RsRlkvV2dZck01?= =?utf-8?B?R0YrVFRRQU9qYlR0TlEwTkRLTjFvVkNCUy9PT2kyalVWQWd4V3ZmUTkvMjVq?= =?utf-8?B?dXdSTGU5RjU4am5iNExpcjA2Q0ZhTDdlYlVUZTRJTkoyVzVDZmtxMS9Zd2Nr?= =?utf-8?B?ZlljQVVvVEI0aHd1OFVIME1xblVOWitiREVRU2s0azhtS0NpdDFYM1g0YzFy?= =?utf-8?B?VXptREs3OVNrdHBzVnRKQU43TkxNS3VpRnU2ZHlVbldRa0VEN0VsbERRRlI5?= =?utf-8?B?QUlBQ0o5NGFNaU1Nc2h4K2dKbVdGWEQwL005eG9RUXc4RERSd3FPVDdBVFo2?= =?utf-8?B?a2VGblNoLzVPUUtiN3JUM2k4aVNKb0pGOXBuSGpxcnMvaG5xQmJxeTNtbFZS?= =?utf-8?B?V0ljaWlGU2EwWkgrZFNUS0V0UW4rdEtiR1lJMWFvWk9FUUJLU0xOaTVKYk5H?= =?utf-8?B?VSt0SGMxSkxxOGVWVFVEQU52NHhvZG1LbGVpQVIrWjRsd3phTFNwc2NTRDBH?= =?utf-8?B?Y09LQ0RMZHY5akZsNGRFNU44Ty83RC9nbWpXQW9XVlJCYmpFTmhiMGhPUHRm?= =?utf-8?B?SkVrcnBPMEZzc1gvKzgxSFJPRUhEeHNaaUhuYWhTdVFabEw2SVMxSlBkWWZJ?= =?utf-8?B?QTZmbW5WTjlqWHdWNmRzR0ZaZFpDSUVKdGg0bmlWVlVTVmprWENHcWx3U3Fw?= =?utf-8?B?TnRtU3pXdGZFZHpKcFBhOWxURXpSNUphazZEYnZWWElCb09TSXFsOTA0elNo?= =?utf-8?B?RDJNWVJlU2cvbzJndFplUzBQQ0ZoM3l5WjZFQUphcjdhTndCZU1wM09ZdDA4?= =?utf-8?B?Vk00TERKckF3UnJ0WW5kWDhrVFUybjcvajV5RGo3aGlrUXhqOHkya0owNDM0?= =?utf-8?B?cDJqT0xxaG5td2tyZUhWYUJMOGFqQXRVanhwak9VUzIvdjFxUGhSSlo4Y2I5?= =?utf-8?Q?0guyqhZl0qGuIpMQXk=3D?=
x-ms-exchange-transport-forked: True
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: base64
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-AuthSource: DM6PR02MB6924.namprd02.prod.outlook.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 6364bcbb-f3d2-4092-3ccf-08d8da8985c5
X-MS-Exchange-CrossTenant-originalarrivaltime: 26 Feb 2021 19:05:46.1809 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: e741d71c-c6b6-47b0-803c-0f3b32b07556
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: ZL3KTgzF3Qxe6pJvec3GO9zSI5gMCoTCged7FqOKg9HssjHUnM9L1+GyVB9wQsRL
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6PR02MB6922
X-OriginatorOrg: att.com
X-TM-SNTS-SMTP: 2E982922555D91346C47BB5FA90BE7BAC063B833D31032EE662802BAD426854A2
X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.369, 18.0.761 definitions=2021-02-26_07:2021-02-26, 2021-02-26 signatures=0
X-Proofpoint-Spam-Details: rule=outbound_policy_notspam policy=outbound_policy score=0 malwarescore=0 clxscore=1015 mlxscore=0 suspectscore=0 spamscore=0 phishscore=0 adultscore=0 lowpriorityscore=0 impostorscore=0 bulkscore=0 priorityscore=1501 mlxlogscore=999 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2009150000 definitions=main-2102260138
Archived-At: <https://mailarchive.ietf.org/arch/msg/ietf/o3eqJNdG6H2VU_03gpMUeEvOYe8>
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: Fri, 26 Feb 2021 19:11:13 -0000

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 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