Re: document writing/editing tools used by IETF

Brian E Carpenter <brian.e.carpenter@gmail.com> Sat, 27 February 2021 20:15 UTC

Return-Path: <brian.e.carpenter@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 D80693A137B for <ietf@ietfa.amsl.com>; Sat, 27 Feb 2021 12:15:47 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.098
X-Spam-Level:
X-Spam-Status: No, score=-2.098 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_FROM=0.001, NICE_REPLY_A=-0.001, RCVD_IN_DNSWL_BLOCKED=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 iPm6pTOzpWCJ for <ietf@ietfa.amsl.com>; Sat, 27 Feb 2021 12:15:45 -0800 (PST)
Received: from mail-pf1-x435.google.com (mail-pf1-x435.google.com [IPv6:2607:f8b0:4864:20::435]) (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 D13B13A1376 for <ietf@ietf.org>; Sat, 27 Feb 2021 12:15:45 -0800 (PST)
Received: by mail-pf1-x435.google.com with SMTP id e3so4561836pfj.6 for <ietf@ietf.org>; Sat, 27 Feb 2021 12:15:45 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=subject:to:references:from:message-id:date:user-agent:mime-version :in-reply-to:content-language:content-transfer-encoding; bh=dYDc8gdm0iwT1FJVgCSkmRo+Hf2dgq1qSVhjwuYdVdE=; b=SYfj7OADFNL3ERzW9aBHdy9ybyrc7XUSmPysOl5Ytw74SLNDSzYalCJFSvRkVyOmm/ FVyNQFL1NHPsarzi/iQ8NjPo0MVmxR1pATPxSJqozlbJ+OscTQHzTojClOO+NH66v1su vP+wnEnis6qmSYje1JiAASp6cF0B80sPW2MmTZhgbhIvcAT0GPQDXLgytBxPfiu8CP6D dLacDlp9A9g9uCWG/nJD3TcPjat11KVw2A7DThRIQdagqyz9Zg7X4CogrNctCb8HgJPr Yv9w0VnIr5ZLgSfiTF7Jb+BvzrjpRB8alNtBxUYc/iGjIasV2ZHv2DGNbhy3jM2pi90j jlyQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=dYDc8gdm0iwT1FJVgCSkmRo+Hf2dgq1qSVhjwuYdVdE=; b=Z8eHAyliKwYaSM/M9+ywZbR+K+TKzHulR3V+Ro/t6dq/drGw4H2D+AfFMXBJCDrnXY PG/mw3A7qOEzbSYuR60EqX1Ce6f7x67muwWbbRKhxMAJZZV12qHTfPrd33unudzcl/G9 JLZp5bu694b6QdM8IUQbWPMwYkCo940i18q996RtFPnnqbGor8O+3OBEzemLdexV5N9L zWQi1G8cRHOij7inlyI9VIOTZWbIaPGOMQQ9yiigR/PEA37H9n1HnSf3PHO3iW0AN7oy Hzyu16HIH1DBJicC77LlxueUjwbmejTIDIKjrQnrO/ZdocOfBeZGlXVdphwTpkn1jEkc /MfQ==
X-Gm-Message-State: AOAM5328YSyDW9nTQqCtNnE4u8SpGsei9IASU0/gHSYqaHN5JwWeUB6q TvHko6DBv01SjoOuWAR4MrX56Ed7PVRJQk5N
X-Google-Smtp-Source: ABdhPJwApFvaT8WSAgCewn0SajlmDG6hA8CzUjaFijB3fGqTGF6l9YhHdbZ284xAhKc48m33ZA5spA==
X-Received: by 2002:a63:4e08:: with SMTP id c8mr7558699pgb.87.1614456944862; Sat, 27 Feb 2021 12:15:44 -0800 (PST)
Received: from [192.168.178.20] ([151.210.131.28]) by smtp.gmail.com with ESMTPSA id c8sm12780217pjv.18.2021.02.27.12.15.43 for <ietf@ietf.org> (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sat, 27 Feb 2021 12:15:44 -0800 (PST)
Subject: Re: document writing/editing tools used by IETF
To: ietf@ietf.org
References: <20210227190200.06ED46F10439@ary.qy>
From: Brian E Carpenter <brian.e.carpenter@gmail.com>
Message-ID: <59efa71b-a5cb-22fc-1696-083292d25de5@gmail.com>
Date: Sun, 28 Feb 2021 09:15:41 +1300
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:60.0) Gecko/20100101 Thunderbird/60.9.1
MIME-Version: 1.0
In-Reply-To: <20210227190200.06ED46F10439@ary.qy>
Content-Type: text/plain; charset="utf-8"
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Archived-At: <https://mailarchive.ietf.org/arch/msg/ietf/JhqFNO3tmTPL0ZTyKEenR9-Um5E>
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: Sat, 27 Feb 2021 20:15:48 -0000

On 28-Feb-21 08:01, John Levine wrote:
> In article <CAMm+LwhOqy2MCmAY5eO2OcpkM99UOS7A5hJaj+thA3SuO+g8FA@mail.gmail.com> you write:
>> Previous attempts to get a discussion going on what tool we would want...
>> haven't exactly been successful. They turn into a github vs mailing list
>> editor war when my interest is quite different.
> 
> I agree that neither mailing lists nor github are ideal for the way the IETF works
> today but I would be very unhappy if we invented yet another bespoke locally maintained
> bunch of software.
> 
> We're strange but it's hard to imagine that we're so strange that there isn't an
> existing package somewhere that will do the job either as is or with minor
> customization.

You'll never, ever get everybody to agree on this topic, because people come at it with different backgrounds, habits and skill sets. So it's futile to expect that everybody will be happy.

I really don't think we'll get anything significantly better than what we have now as the reference/archival/canonical format, which is xml2rfcv3. Why? Because it expresses what our document series needs in the way of metadata. That's all. It's ugly to look at, but we don't expect typical readers to look at it. It's ugly to edit, which many of us don't actually care about (I'm perfectly happy to edit it with XML Copy Editor, as it happens), but we have kramdown to avoid that ugliness.

That's quite separate from how we manage collaborative editing. GitHub is one way, and it suits some people. Quite a few of us used Subversion in the past; we did in fact use Subversion and trac as the basis for the ION documents experiment. If you want to see what it looked like:
https://web.archive.org/web/20080216034049/http://www.ietf.org/IESG/content/ions.html
IMHO, mixing Subversion and trac was complicated and confusing. I'm willing to believe that GitHub is better.

I've used "track changes" for collaborative development of .doc and .docx documents, and found it confusing and error-prone when more than say, two, authors were involved.

I am quite confident you will never get broad consensus on the best approach to collaborative editing. As long as we stick to BCP25, this doesn't matter, because editing is only a tool and not a method of determining consensus. Allowing individual authoring teams and WGs to choose the method of collaborative editing that suits them best seems good to me.

   Brian