IETF Logo Mail Archive

Re: document writing/editing tools used by IETF

Carsten Bormann <cabo@tzi.org> Sun, 28 February 2021 23:35 UTC

Return-Path: <cabo@tzi.org>
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 97E433A0D8E for <ietf@ietfa.amsl.com>; Sun, 28 Feb 2021 15:35:44 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -0.018
X-Spam-Level:
X-Spam-Status: No, score=-0.018 tagged_above=-999 required=5 tests=[RCVD_IN_DNSWL_BLOCKED=0.001, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
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 AmIhBi09LIp9 for <ietf@ietfa.amsl.com>; Sun, 28 Feb 2021 15:35:42 -0800 (PST)
Received: from gabriel-vm-2.zfn.uni-bremen.de (gabriel-vm-2.zfn.uni-bremen.de [134.102.50.17]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 1C5853A0D91 for <ietf@ietf.org>; Sun, 28 Feb 2021 15:35:30 -0800 (PST)
Received: from [192.168.217.123] (p5089a828.dip0.t-ipconnect.de [80.137.168.40]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by gabriel-vm-2.zfn.uni-bremen.de (Postfix) with ESMTPSA id 4Dpfrt3B39zygP; Mon, 1 Mar 2021 00:35:26 +0100 (CET)
Content-Type: text/plain; charset="utf-8"
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.120.23.2.4\))
Subject: Re: document writing/editing tools used by IETF
From: Carsten Bormann <cabo@tzi.org>
In-Reply-To: <3196.1614554436@localhost>
Date: Mon, 01 Mar 2021 00:35:28 +0100
Cc: ietf@ietf.org
X-Mao-Original-Outgoing-Id: 636248128.0052249-8f7b783a50e8fe1abfae9aa11cf90066
Content-Transfer-Encoding: quoted-printable
Message-Id: <8E1799FF-1E8A-4ACA-BCF8-A01F1EF24CB8@tzi.org>
References: <20210227190200.06ED46F10439@ary.qy> <4064.1614454347@localhost> <s1f0vo$ejp$1@gal.iecc.com> <3196.1614554436@localhost>
To: Michael Richardson <mcr+ietf@sandelman.ca>
X-Mailer: Apple Mail (2.3608.120.23.2.4)
Archived-At: <https://mailarchive.ietf.org/arch/msg/ietf/zY0LGRf_deI89Udny8sbjrJaua4>
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: Sun, 28 Feb 2021 23:35:45 -0000

> On 2021-03-01, at 00:20, Michael Richardson <mcr+ietf@sandelman.ca> wrote:
> 
> You should highlight changes 

…by writing something like
https://www.rfc-editor.org/rfc/rfc8949.html#section-appendix.g

(Indication of verbatim changes can be done by a diff tool — let the computer do the counting.
But the computer usually does not know the rationale for a change…
That’s why you need *changesets* and *commit comments*, best coupled to a discussion thread.)

I think much of the discussion of collaboration tools has a blub problem.
Please see http://www.paulgraham.com/avg.html "Beating the Averages" — ignore the annoying self-patting, but the really important concept of blub comes up about 1/3 down.

Grüße, Carsten

Aargh, I’m increasing my ietf@ article count again

v2.23.0 | Report a Bug | By Email