From nobody Tue Sep  1 14:55:44 2020
Return-Path: <jay@ietf.org>
X-Original-To: tools-arch@ietfa.amsl.com
Delivered-To: tools-arch@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 3BA123A110C for <tools-arch@ietfa.amsl.com>; Tue,  1 Sep 2020 14:55:43 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.899
X-Spam-Level: 
X-Spam-Status: No, score=-1.899 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, 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 Sy9ATxW2I_3K; Tue,  1 Sep 2020 14:55:41 -0700 (PDT)
Received: from jays-mbp.localdomain (unknown [158.140.230.105]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPSA id 8E1443A110B; Tue,  1 Sep 2020 14:55:40 -0700 (PDT)
Content-Type: text/plain; charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.80.23.2.2\))
From: Jay Daley <jay@ietf.org>
In-Reply-To: <2062f219-5b09-46aa-bf47-ea55f287e142@www.fastmail.com>
Date: Wed, 2 Sep 2020 09:55:38 +1200
Cc: tools-arch@ietf.org
Content-Transfer-Encoding: quoted-printable
Message-Id: <4C30E7BC-F0F1-495A-9490-675BB3D2407A@ietf.org>
References: <5841e863-80b8-42a8-a989-98bd1ad8e837@www.fastmail.com> <BBE0CB97-6495-4B42-8A9B-5B2CC3226782@ietf.org> <2062f219-5b09-46aa-bf47-ea55f287e142@www.fastmail.com>
To: Martin Thomson <mt@lowentropy.net>
X-Mailer: Apple Mail (2.3608.80.23.2.2)
Archived-At: <https://mailarchive.ietf.org/arch/msg/tools-arch/VD-JbPt3yq3AWCDG5-MFes4A9xU>
Subject: Re: [Tools-arch] Document Production Methods
X-BeenThere: tools-arch@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Tools Architecture and Strategy Team  <tools-arch.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/tools-arch/>
List-Post: <mailto:tools-arch@ietf.org>
List-Help: <mailto:tools-arch-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=subscribe>
X-List-Received-Date: Tue, 01 Sep 2020 21:55:43 -0000

I=E2=80=99m not aware of markdown supporting semantic markup or anything =
more than basic layout markup (excluding embedded HTML).  Absent that I =
can=E2=80=99t see any alternative to XML for that stage.  That=E2=80=99s =
not to suggest that XML is the best for the other stages (it isn=E2=80=99t=
).

One important thing to note is that plain (standard?) markdown is far =
from sufficient to write an IETF document.  kramdown-rfc uses a mixture =
of markdown, yaml and custom extensions, while mmark adds the following =
list of extensions on top of an already extended markdown processor:

> 	=E2=80=A2 TOML titleblock.
> 	=E2=80=A2 Including other files.
> 	=E2=80=A2 More enumerated lists and task-lists.
> 	=E2=80=A2 Table and codeblock captions.
> 	=E2=80=A2 Quote attribution (quote "captions").
> 	=E2=80=A2 Table footers, header and block tables.
> 	=E2=80=A2 Subfigures.
> 	=E2=80=A2 Inline Attribute Lists.
> 	=E2=80=A2 Indices.
> 	=E2=80=A2 Citations.
> 	=E2=80=A2 Abstract/Preface/Notes sections.
> 	=E2=80=A2 Parts.
> 	=E2=80=A2 Asides.
> 	=E2=80=A2 Main-, middle- and backmatter divisions.
> 	=E2=80=A2 Math support.
> 	=E2=80=A2 Example lists.
> 	=E2=80=A2 HTML Comment parsing.
> 	=E2=80=A2 BCP14 (RFC2119) keyword detection.
> 	=E2=80=A2 Include raw XML references.
> 	=E2=80=A2 Abbreviations.
> 	=E2=80=A2 Super- and subscript.
> 	=E2=80=A2 Callouts in code blocks.

This suggests that what matters to the IETF first and foremost is the =
document schema (https://github.com/rfc-format/v3grammar) in which case =
it may be useful think about a standard subset of the full schema that =
is all that is needed for stage 2 and a standard way of supporting that =
in any markdown+ tool.

Jay


> On 1/09/2020, at 5:21 PM, Martin Thomson <mt@lowentropy.net> wrote:
>=20
> That's a fair summary.
>=20
> I would say however that you might be overstating the XML thing.  =
Those who designed the v3 format might believe that it is all needed, =
but I am less certain of the value of it all.  What is true is that this =
is what we have.
>=20
> What I think is important to preserve across conversions is the text.  =
The dressings (boilerplate, use of <aside> rather than whatever =
formatting convention you had, adding <bcp14> tags, and all that mess) =
aren't what are being negotiated.  Edits of the language for clarity =
have value, but dressing it up in XML isn't likely to result in an =
artifact that has significantly more inherent value than the input.
>=20
> As long as down-conversion retains text, and the nature of what is =
erased is understood, then we probably don't lose much by doing that.
>=20
> On Tue, Sep 1, 2020, at 13:52, Jay Daley wrote:
>> If I take what you=E2=80=99ve written and rearrange it in a different =
way, you=20
>> are describing three different stages of document authoring each of=20=

>> which has a different use case and each use case would be better=20
>> supported by a different format.
>>=20
>> # Stage one - initial authoring
>> This is the initial production of the document either by one person =
or=20
>> a small group, which only requires basic revision tracking and=20
>> comments.  As you say, that is better suited to Google Docs or=20
>> something similar for fast, easy collaboration.
>>=20
>> # Stage two - group text revision
>> This the laborious process of multiple contributors working with=20
>> changes across the document.  Again, as you say, that works best with=20=

>> something as close to plain text as possible, such as markdown as the=20=

>> markup only gets in the way and XML is so much markup.
>>=20
>> # Stage three - pre-publication preparation
>> This consists mainly of filling out boilerplate sections =
(contributors=20
>> etc), adding semantic annotation and layout control, with text =
changes=20
>> focused on clarity/language etc not substance.  The moment we get =
into=20
>> semantic annotation and layout control we need complex markup such as=20=

>> XML.  The boilerplate stuff and text cleanup could be done in stage=20=

>> two-point-five before the XML comes into it.
>>=20
>>=20
>> Automated format translation from one stage to the next higher stage =
is=20
>> easy provided conventions are followed in both stages one and two,=20
>> which is easy enough with templates. =20
>>=20
>> Translating a document back a stage (your XML to markdown convertor) =
is=20
>> where more thought is required both in terms of what processes this=20=

>> will be used for as well as the technical side.  For example, is this=20=

>> intended to be a one-way translation so that any semantic and layout=20=

>> markup is lost, or is it meant to be a reversible process where the=20=

>> markdown is "extracted" from the XML, then edited and the =
"reinserted"=20
>> into the XML?  A simple XML to markdown convertor is not hard [1],=20
>> while the two way is more complex but still doable.
>>=20
>> Jay
>>=20
>> [1]  In my current role I don=E2=80=99t do technology, but when I =
did, XML to=20
>> [=E2=80=A6] conversion was something I did=20
>> https://github.com/JayDaley/XML-to-JSON-in-XSLT
>>=20
>>=20
>>> On 31/08/2020, at 6:09 PM, Martin Thomson <mt@lowentropy.net> wrote:
>>>=20
>>> There has been a bunch of discussion recently on the rfced-future =
list about the tools that people use to produce documents.  It seems =
like this is one of the major areas in which we could provide some =
input.  Here's my initial suggestion.
>>>=20
>>>=20
>>> # Production Methods
>>>=20
>>> The point of this document is to examine how the tools we use to =
produce a document influence the style of collaboration we use.  And to =
examine where there are gaps in the process that might be addressed with =
better tooling.
>>>=20
>>> ## Straight to XML
>>>=20
>>> This is how I used to operate.  It is an tolerable choice, but not a =
great one.  XML is fiddly to the point of being user-hostile.  Add to =
that the (recent) instability in the format and I would argue that this =
is not a good format to author documents in.
>>>=20
>>> I understand that this is (now) how the RPC operates, so this is an =
important option to consider.  It is possible that, due to our choice of =
publication format, that this remains important as the single place on =
which we can focus attention.
>>>=20
>>> For specialized tooling, this might be the best format to =
concentrate on.  For instance, tools that validate code fragments could =
target the XML format and rely on conversion to XML from other formats.  =
This isn't perfect as, for instance, none(?) of the conversion tools =
preserve mappings to line numbers in source, so finding errors can be =
frustrating.  However, being able to target a single format for a tool =
can save on development effort.
>>>=20
>>> ## Markdown
>>>=20
>>> I'm aware of two variants here (kramdown-rfc2629 and mmark), both of =
which are easy to use and provide native support for all the important =
parts of a functional document.  There are some weak points, but they =
are quite minor.  The overall experience of authoring in markdown is =
excellent.
>>>=20
>>> This is how I currently recommend that people work on documents.  =
You might not always *start* here (see below), but you should probably =
spend most of your time here.  I find that that most documents can start =
and end here anyway.
>>>=20
>>> The main open question I have is what level of support is provided =
once the collaborative portion of the process ends and the document =
moves to editing and publication.  To my mind, the ideal situation is =
that the original authoring format is retained and final edits are done =
to that format.  This would allow for working groups to pick up =
something that is close to the final publication form and produce a =
revision.
>>>=20
>>> This is not the model the RPC currently adopts.  Only XML is =
accepted for editing.  If we want to allow for a single set of tools for =
things like spell checking, this might be the right answer.  However, =
maintaining continuity for editors is important, and editors that want =
markdown should be provided that option.  A converter from XML to =
markdown might be all that is needed.  Having perfect down-conversion is =
possible, but likely to be unworkable.  An imperfect conversion might be =
OK provided that there is no loss of semantic information, or - worst =
case - lost semantics could be logged for manual examination.
>>>=20
>>> ## Microsoft Word/Google Docs
>>>=20
>>> Producing content collaboratively using Word or Docs is pretty =
damned good.  Inline comments and suggestions are two features I rely on =
a massive amount in my day-to-day work.  Both tools do very well at =
this.
>>>=20
>>> However, I don't think that we need a tool that has this level of =
fast iteration capability.  This style of interaction doesn't scale out =
very well, so I believe that it is only useful during early stages of =
document production.  That is, when there is a small group of people who =
are collaborating on an initial revision of a document.  In that case, =
the power that these tools provide is of great use.  Commentary and =
interactive editing are hugely useful at this stage of the process. =20
>>>=20
>>> You might also consider these tools for design teams or =
collaborating on small edits to an existing document.
>>>=20
>>> What I have found in the past is that producing a first draft of a =
document using these tools is great.  Once more open collaboration is =
required, it is better to have a textual artifact in a revision control =
system (see RFC 8874).
>>>=20
>>> Revision control and issue tracking in particular allow you to =
better control changes and - as the process evolves - give you much =
better visibility into what has happened and why.  Using a text-based =
format is a precondition of getting support from these tools.
>>>=20
>>> For transfer into markdown, there are online tools that can convert =
a simple Word document (in .doc or .docx format) into markdown.  =
https://word2md.com uses https://github.com/benbalter/word-to-markdown, =
but there are others.  This needs a little massaging to cleanup, which =
could be mechanized if this happens often, but the changes are usually =
small.  I know of one case where an extension to Google Docs was written =
to do this conversion.  The first draft of RFC 8752 was produced using =
this method and it worked very well.
>>>=20
>>> Change tracking is a feature I've seen used a lot in other bodies =
that exclusively use Word.  I don't think that this feature works =
especially well relative to the text-based diffs we routinely use.
>>>=20
>>> ### Microsoft Word Template
>>>=20
>>> Joe Touch maintains a world template that produces text in the paged =
text form of yore.  I think that this results in a terrible process.  =
Even if it were to able to produce XML, it does not produce an artifact =
that can be collaborated on easily. =20
>>>=20
>>> Once you beyond a small group of collaborators, Word is not as good =
as textual formats at managing collaboration.  Authoring in Word at best =
follows a collaboration model where you have a single editor (or, if you =
are especially lucky, a tight editor team) and a group of supplicants =
who can ask the editor to make changes.  I've seen this form of process =
in other groups (3GPP and OMA in particular) and it's not the sort of =
standards collaboration I would wish on anyone.  There is a strong =
tendency for editors to become gatekeepers anyway, but this reinforces =
the privilege and control of that position as every change needs to be =
touched by an editor.
>>>=20
>>> People also need to have accounts with the online service in order =
to collaborate effectively, which has proven to be a real barrier in =
practice.
>>>=20
>>> ## Other Tools
>>>=20
>>> There is a long tail here, obviously.  The list of "others" includes =
nroff, outline.el, and others I am just not aware of.  I have no idea =
how widespread any of these tools are, but unless presented with =
evidence that suggests lots of use, I don't think we need to entertain =
these.
>>>=20
>>> My suggestion is that those that can produce XML should do so =
promptly.  Those that can only produce text, like the Word template, =
might find a path to markdown easier.
>>>=20
>>> # Recommendation
>>>=20
>>> The overriding theme here is how easy it is to collaborate.  In the =
context of the IETF processes, that is to achieve consensus around the =
content of a single artifact.
>>>=20
>>> I would argue that markdown is the best tool we currently have for =
this.  First-class support for markdown in our processes is something we =
should aim for.  Many of the utilities that support markdown will also =
support XML, and some people will produce XML, so a modest effort to =
support XML would be appreciated.
>>>=20
>>> As textual formats, this allows us to use many of the same processes =
and tools that are available for source code.  This should be familiar =
to many of the people we hope will contribute.
>>>=20
>>> For general tool support, targeting XML alone might be cheaper in =
terms of addressing the largest number of users.  But generic support =
for text-based formats would be ideal.
>>>=20
>>> I am also going to deliberately suggest that no support is offered =
for other authoring formats.  We might respect the choice of individuals =
to use other formats for authoring, but those people cannot expect =
others to carry the cost of their choices.  That means providing =
encouragement to use the standard tools.
>>>=20
>>> We might provide an on-ramp for people who want to do initial =
authoring in tools that are better suited to rapid collaboration.  But =
this should concentrate on as few options as possible.
>>>=20
>>> # Potential New Tools
>>>=20
>>> A tool that converts from XML to markdown would be a great addition =
to our toolset.  This would allow people to pick up XML documents that =
were produced from a variety of formats and restart collaboration in a =
format that is most accessible.
>>>=20
>>> A tool that converts from text to XML or markdown would be the only =
other addition we might consider.   I don't know if one of these exists =
already.  Such a tool might exist, it's fairly easy to script something.
>>>=20
>>> Improving support for conversion from word to markdown would be =
helpful for those who want to use Microsoft Word or Google Docs.  This =
might also help get people migrate from the Word template as well.
>>>=20
>>> --=20
>>> Tools-arch mailing list
>>> Tools-arch@ietf.org
>>> https://www.ietf.org/mailman/listinfo/tools-arch
>>>=20
>>=20
>> --=20
>> Jay Daley
>> IETF Executive Director
>> jay@ietf.org
>>=20
>=20
> --=20
> Tools-arch mailing list
> Tools-arch@ietf.org
> https://www.ietf.org/mailman/listinfo/tools-arch

--=20
Jay Daley
IETF Executive Director
jay@ietf.org


From nobody Tue Sep  1 19:36:23 2020
Return-Path: <johnl@iecc.com>
X-Original-To: tools-arch@ietfa.amsl.com
Delivered-To: tools-arch@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 5F9B13A0A56 for <tools-arch@ietfa.amsl.com>; Tue,  1 Sep 2020 19:36:21 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.851
X-Spam-Level: 
X-Spam-Status: No, score=-1.851 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, HEADER_FROM_DIFFERENT_DOMAINS=0.249, 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=iecc.com header.b=dG73B9iJ; dkim=pass (2048-bit key) header.d=taugh.com header.b=TJd3WrIT
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 ssX1ff80Mh29 for <tools-arch@ietfa.amsl.com>; Tue,  1 Sep 2020 19:36:20 -0700 (PDT)
Received: from gal.iecc.com (gal.iecc.com [IPv6:2001:470:1f07:1126:0:43:6f73:7461]) (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 C35E43A09D9 for <tools-arch@ietf.org>; Tue,  1 Sep 2020 19:36:19 -0700 (PDT)
Received: (qmail 60365 invoked from network); 2 Sep 2020 02:36:18 -0000
DKIM-Signature: v=1; a=rsa-sha256; c=simple; d=iecc.com; h=date:message-id:from:to:cc:subject:in-reply-to:mime-version:content-type:content-transfer-encoding; s=ebca.5f4f0522.k2009; bh=V7iSU+zrWxGJIXndRNmbWpezcbzu6eRCpVu9uEomvAY=; b=dG73B9iJ8U3P0Uk+6PkpMUzxdXvBt0mitCsNW/3zp9Do2mlmtszXfDB4VntvnMbYZz9+tia4ACCStNn8LSVuTW9CkM4t6BzlAS3bXRAWV+fQH+p3i/BVgxuMfGp1kUDeoL4Qdzbb7eqIes142+8jGicHEbwxzrRksDH23B77hc7YI/pgOUx1NfpcnMn6jXv0tpYjqw39nXjccwB+K3XaNrLX7Mc4sPdU/B1x+g3k+2o9eI0YjWL4oagzT2YawipgV6TIELbgxiVAT+FVsgE4EvUCmS83jrK3nivbELBaWSOWWlpXIpMcNJA+oIc+ETJNde+I1cTSZqy7f1RERcAquQ==
DKIM-Signature: v=1; a=rsa-sha256; c=simple; d=taugh.com; h=date:message-id:from:to:cc:subject:in-reply-to:mime-version:content-type:content-transfer-encoding; s=ebca.5f4f0522.k2009; bh=V7iSU+zrWxGJIXndRNmbWpezcbzu6eRCpVu9uEomvAY=; b=TJd3WrITsM2iS+29aq0AqGn//h6Ab9iFbvXhIHeE9327Tyt4nNKYqzFvfxW9O9f0UE8ojvWnHHtDocWvIHDDIcaJsojioJXSiQ/vZGLX5f3woCqH7SUOEf0kUURqYPGlQQNE5nx00GEZMRe0Jei+OTZ0KHyp1HZfwSXnJe4NswPRWZ++EnHFxtLreCM7GJv9f5f8bk/RvWQiRMsfXHB9irm65AmtLae3ckZ/+mslmsCFP+df27oiOiY+6l80+rAij6DWfv1aohPaEZDrzg0Wba7uwJs57TETEoSFeAmNnu8YrH3Ot5lNjkLZTtOu0esCJix0z7B4kYaKo58IaBoS6A==
Received: from ary.qy ([IPv6:2001:470:1f07:1126::78:696d:6170]) by imap.iecc.com ([IPv6:2001:470:1f07:1126::78:696d:6170]) with ESMTPS (TLS1.2 ECDHE-RSA AES-256-GCM AEAD) via TCP6; 02 Sep 2020 02:36:17 -0000
Received: by ary.qy (Postfix, from userid 501) id 66BA41F5F442; Tue,  1 Sep 2020 22:36:17 -0400 (EDT)
Date: 1 Sep 2020 22:36:17 -0400
Message-Id: <20200902023617.66BA41F5F442@ary.qy>
From: "John Levine" <johnl@taugh.com>
To: tools-arch@ietf.org
Cc: mt@lowentropy.net
In-Reply-To: <2062f219-5b09-46aa-bf47-ea55f287e142@www.fastmail.com>
Organization: Taughannock Networks
X-Headerized: yes
Mime-Version: 1.0
Content-type: text/plain; charset=utf-8
Content-transfer-encoding: 8bit
Archived-At: <https://mailarchive.ietf.org/arch/msg/tools-arch/9iyWu1FoPBXYTCje-Tg6y2LN2Ss>
Subject: Re: [Tools-arch] Document Production Methods
X-BeenThere: tools-arch@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Tools Architecture and Strategy Team  <tools-arch.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/tools-arch/>
List-Post: <mailto:tools-arch@ietf.org>
List-Help: <mailto:tools-arch-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 02 Sep 2020 02:36:21 -0000

In article <2062f219-5b09-46aa-bf47-ea55f287e142@www.fastmail.com> you write:
>That's a fair summary.
>
>I would say however that you might be overstating the XML thing.  Those who designed the v3 format might believe
>that it is all needed, but I am less certain of the value of it all.  What is true is that this is what we have.

I think we underestimated how hard it is to do automated typsetting
that produces good looking results so we ended up with a whole lot of
very complex tagging to let people say in great detail how they want
things to look. We also put in a lot of semantic tags, e.g., this is a
picture, that is sourcecode, this other thing is someone's name, which
may be useful for future automated processing but we don't know yet.

>What I think is important to preserve across conversions is the text.

One of the few things that XML makes simple is to tell what is a tag
and what is text.

R's,
John


From nobody Tue Sep  1 20:57:43 2020
Return-Path: <mt@lowentropy.net>
X-Original-To: tools-arch@ietfa.amsl.com
Delivered-To: tools-arch@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id DB3F93A0AF9 for <tools-arch@ietfa.amsl.com>; Tue,  1 Sep 2020 20:57:41 -0700 (PDT)
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, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=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=lowentropy.net header.b=r1uwnfDm; dkim=pass (2048-bit key) header.d=messagingengine.com header.b=cNcVodSz
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 WcE05DYtfOLi for <tools-arch@ietfa.amsl.com>; Tue,  1 Sep 2020 20:57:40 -0700 (PDT)
Received: from out1-smtp.messagingengine.com (out1-smtp.messagingengine.com [66.111.4.25]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id AC6E53A0AF8 for <tools-arch@ietf.org>; Tue,  1 Sep 2020 20:57:40 -0700 (PDT)
Received: from compute2.internal (compute2.nyi.internal [10.202.2.42]) by mailout.nyi.internal (Postfix) with ESMTP id 0372C5C01F1; Tue,  1 Sep 2020 23:57:40 -0400 (EDT)
Received: from imap10 ([10.202.2.60]) by compute2.internal (MEProxy); Tue, 01 Sep 2020 23:57:40 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lowentropy.net; h=mime-version:message-id:in-reply-to:references:date:from:to :subject:content-type; s=fm3; bh=z+/VCUSMIRbyiN3Kaq5EM+0rMOllqOu pGJO9+0CzJqc=; b=r1uwnfDmfcOiz/svR93Jj3wysIVIcZAzDWqWoED/s3M0yaU atGgoowpxBWPndD4dRKMeKohk5iwYESFie2G3MQeCjInAr2dcZB1Z1xd/xj4Z4ka rh5o5eS/wMrVAKAVXE3II+3B2oggWM7/69PbJTc6EaiHIwDwqP+EgJ+gl2ko0PZL MW/vHaDnOY3agjcPqiKgk1tHoEJXFXdtjK6ZST4vkrzgOclyI+LZwK8E9rqzvthj oeELmh+ADR10ERnsLmALeMRsqgyCMtViJaPzkukCP9E+SSkUtrTZlYFcrNjBzg71 lWTMjG1/ll4SEFiziy2ZI9fohWGxpr0L5IruPoA==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm3; bh=z+/VCU SMIRbyiN3Kaq5EM+0rMOllqOupGJO9+0CzJqc=; b=cNcVodSzvQoT30SqpqEvRn THf/NDYWiWXrXskAgoc9a58Y/IdkzBo14uJ83ztS4mhuc8UamAGB+24Wn8Wi8UAw NG/NpG/u6/PeuUpcBkD3YjmxMAm3OIN4M8nbRvEC/u9ZlShVGB/iflfNFR/3YrkK ViDOuAzhj4d2qtyLbUnRgPFcVXL3AL1hxVrfMd89WXLkoXijvRW2jxpsfDvLAHuH Be43frkXBOb9qGJkmhF0PCSvfwQFtiob0YlJOzie+JjBObg3GWel8jToIh/OwZw7 B21ZHpzX3fJunzCG4eDkIrqx7EgqiMA976bZh0OrEiSuiUEhsYU7JRZ06VYI+Jaw ==
X-ME-Sender: <xms:MxhPX9g5Vu2shRuXKMGqqw8SDY0whl8Tuwu087OJeX0KLLaYNHVyUA> <xme:MxhPXyDNxHC4YjiVXzg9LzLsr1NIpNb91NFhla5h-Oqpu3ItfIHsFJFDE0HimBqA1 U0gkW682TR-D3pL3g4>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduiedrudefkedgjeejucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhepofgfggfkjghffffhvffutgesthdtredtreertdenucfhrhhomhepfdforghr thhinhcuvfhhohhmshhonhdfuceomhhtsehlohifvghnthhrohhphidrnhgvtheqnecugg ftrfgrthhtvghrnhepkeetueeikedtkeelfeekvefhkeffvedvvefgkefgleeugfdvjeej geffieegtdejnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrh homhepmhhtsehlohifvghnthhrohhphidrnhgvth
X-ME-Proxy: <xmx:MxhPX9Fu9qSiWOMcAbqIVqILqq2FnsdGYdSaxnViq0TDp00fIIkKpg> <xmx:MxhPXyRhDFAthOl1V0Lxn4cniX5tA56LlbP3xLfFK4nrWeE-LdwlbA> <xmx:MxhPX6x4_zUqFLCUvK0UZt0Hr7UD8vsRpBdVyA5NI47E7dgNbokKpQ> <xmx:MxhPX_uDKbpedZOvw3dW7q6XxWbXNEg8-o3tW5qofKjglAQ_ZzAz3Q>
Received: by mailuser.nyi.internal (Postfix, from userid 501) id 4785B20064; Tue,  1 Sep 2020 23:57:39 -0400 (EDT)
X-Mailer: MessagingEngine.com Webmail Interface
User-Agent: Cyrus-JMAP/3.3.0-248-gcd102cb-fm-20200901.001-gcd102cb9
Mime-Version: 1.0
Message-Id: <88deacab-2966-4a7f-a28f-b7c19abe3a2f@www.fastmail.com>
In-Reply-To: <20200902023617.66BA41F5F442@ary.qy>
References: <20200902023617.66BA41F5F442@ary.qy>
Date: Wed, 02 Sep 2020 13:57:14 +1000
From: "Martin Thomson" <mt@lowentropy.net>
To: "John R Levine" <johnl@taugh.com>, tools-arch@ietf.org
Content-Type: text/plain
Archived-At: <https://mailarchive.ietf.org/arch/msg/tools-arch/3s3IfzvqRauzPbIngFbcwRCfrs8>
Subject: Re: [Tools-arch] Document Production Methods
X-BeenThere: tools-arch@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Tools Architecture and Strategy Team  <tools-arch.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/tools-arch/>
List-Post: <mailto:tools-arch@ietf.org>
List-Help: <mailto:tools-arch-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 02 Sep 2020 03:57:42 -0000

On Wed, Sep 2, 2020, at 12:36, John Levine wrote:
> I think we underestimated how hard it is to do automated typsetting
> that produces good looking results so we ended up with a whole lot of
> very complex tagging to let people say in great detail how they want
> things to look. We also put in a lot of semantic tags, e.g., this is a
> picture, that is sourcecode, this other thing is someone's name, which
> may be useful for future automated processing but we don't know yet.

I guess what I'm challenging here is the inherent value of those annotations.

For the typesetting stuff, as that is tied to a very specific instance, attempting to preserve those as text is subsequently changed might be counterproductive.

For the semantic stuff, as they are not the product of any negotiation/consensus process, it is unlikely that they have any special status.  As such, I suggest that they exist on much the same level as other unofficial markings.  Useful or not, they aren't representative of the artifact we are looking to preserve.  They are only useful to the extent that they allow us to better communicate about that artifact, to which you next point might be the most salient in this regard...

> One of the few things that XML makes simple is to tell what is a tag
> and what is text.

That unfortunately isn't always respected, as I recently learned.  But that's a tooling issue that is easily rectified.


From nobody Wed Sep  2 08:51:23 2020
Return-Path: <silviamikhail@gmail.com>
X-Original-To: tools-arch@ietfa.amsl.com
Delivered-To: tools-arch@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 42CC13A11BF for <tools-arch@ietfa.amsl.com>; Wed,  2 Sep 2020 08:51:22 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.096
X-Spam-Level: 
X-Spam-Status: No, score=-2.096 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, HTML_MESSAGE=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 u_cizw5eVEDj for <tools-arch@ietfa.amsl.com>; Wed,  2 Sep 2020 08:51:20 -0700 (PDT)
Received: from mail-lj1-x231.google.com (mail-lj1-x231.google.com [IPv6:2a00:1450:4864:20::231]) (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 2FE513A1226 for <tools-arch@ietf.org>; Wed,  2 Sep 2020 08:51:17 -0700 (PDT)
Received: by mail-lj1-x231.google.com with SMTP id e11so6532119ljn.6 for <tools-arch@ietf.org>; Wed, 02 Sep 2020 08:51:17 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025;  h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=8W+PYpUqqIPwjE+6GIBq7skZvnv2DVVZvKr5hVwDrMw=; b=AhOWjkKIIgRcqmt4jNhTC5mqpdyKt1MI/w6yL+HPfR0abunLj7kg10d8UNTcGMhkcE S8/QliMz4+7Mikt1p0WCCgi3ol7FRkqrj8zt4TOvbyfJfD72W+89AS3rBNF9polhuZZ4 CiBAFSUYKyW7FJ2LVfbhdCqGKiEoQJXjX/+CFcW545t9YjPn7neyzrdK8kyls2Qgla/S WTRwin6vQAW9VemCczFLfrA2EW0Qz1J9SOKh546taYrylKkqlEbQzGUyTwehGOFEK1F3 iCfE1WopytUTDwXNakb3cWeWrc/7tWQ520jOI9KLPvbdOnS4DgZ7BLvHDTeUPl1wkpOH YNBQ==
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:from:date :message-id:subject:to:cc; bh=8W+PYpUqqIPwjE+6GIBq7skZvnv2DVVZvKr5hVwDrMw=; b=fg012uml+6NVnA1tai/H9H2XiKXVcDj1gJeDsznfcaWYsVbTgYBLnMeOBJPxlhi8cE aToHHDvFyo5kHbL2ZnWdAsCltBZKRuecbhaqgevQNy7MSsVYcMTyyktG/M4RoQ+r2qk+ GE2glHnjZWK2ONFWfhaYZ8unfRxuZDd7WVoVKvsNlUCGnAAUurfernf7Azq1l5FhGLAW 7LL1mantoDXMP2RoJjfrVooC0ykk6+weAnnKfWQnHj/4lbGXkCoFUyjs/SIEi33A26vp f89u9eVF135hJKcDf0k24EbcAXxzO9jpngtdA12QS7fS7xCetd2zkuxKALLo3XQqpLxG 7P0A==
X-Gm-Message-State: AOAM532xH4gRL3LB7m4LjmDEFHRNvKSJEbveBber2LPCuaE+W+4TIvCp s9ifgvT/h1/tB7kIypGqnC7ALdJlSotf38QUOaZQ5+vlKus=
X-Google-Smtp-Source: ABdhPJy4R6hYUtSt7IKitvXz/J39+fshzMfacKxMSVU8jmgUJK3V09Mw5IvbmCgj42dHPVvTu26K3hJ4MKbdufBJGn8=
X-Received: by 2002:a2e:a483:: with SMTP id h3mr3604703lji.76.1599061875231; Wed, 02 Sep 2020 08:51:15 -0700 (PDT)
MIME-Version: 1.0
References: <20200902023617.66BA41F5F442@ary.qy> <88deacab-2966-4a7f-a28f-b7c19abe3a2f@www.fastmail.com>
In-Reply-To: <88deacab-2966-4a7f-a28f-b7c19abe3a2f@www.fastmail.com>
From: Silvia Botros <silviamikhail@gmail.com>
Date: Wed, 2 Sep 2020 08:51:04 -0700
Message-ID: <CA+tzEMB8Qj=b2dg-QoMtze7zWvHraxsAp=bGR-itEi_fU+Ly2A@mail.gmail.com>
To: Martin Thomson <mt@lowentropy.net>
Cc: John R Levine <johnl@taugh.com>, tools-arch@ietf.org
Content-Type: multipart/alternative; boundary="0000000000000c121a05ae569bd8"
Archived-At: <https://mailarchive.ietf.org/arch/msg/tools-arch/34gchycSCv4Urx2Gl6zHMvdWnn4>
Subject: Re: [Tools-arch] Document Production Methods
X-BeenThere: tools-arch@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Tools Architecture and Strategy Team  <tools-arch.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/tools-arch/>
List-Post: <mailto:tools-arch@ietf.org>
List-Help: <mailto:tools-arch-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 02 Sep 2020 15:51:22 -0000

--0000000000000c121a05ae569bd8
Content-Type: text/plain; charset="UTF-8"

should we consider in this conversation existing IDEs/editors people may
use to create these artifacts? it seems to me that Markdown editors are far
more on the rise than XML and that would be part of the equation for
someone about to start a document.

- SB


On Tue, Sep 1, 2020 at 8:57 PM Martin Thomson <mt@lowentropy.net> wrote:

>
>
> On Wed, Sep 2, 2020, at 12:36, John Levine wrote:
> > I think we underestimated how hard it is to do automated typsetting
> > that produces good looking results so we ended up with a whole lot of
> > very complex tagging to let people say in great detail how they want
> > things to look. We also put in a lot of semantic tags, e.g., this is a
> > picture, that is sourcecode, this other thing is someone's name, which
> > may be useful for future automated processing but we don't know yet.
>
> I guess what I'm challenging here is the inherent value of those
> annotations.
>
> For the typesetting stuff, as that is tied to a very specific instance,
> attempting to preserve those as text is subsequently changed might be
> counterproductive.
>
> For the semantic stuff, as they are not the product of any
> negotiation/consensus process, it is unlikely that they have any special
> status.  As such, I suggest that they exist on much the same level as other
> unofficial markings.  Useful or not, they aren't representative of the
> artifact we are looking to preserve.  They are only useful to the extent
> that they allow us to better communicate about that artifact, to which you
> next point might be the most salient in this regard...
>
> > One of the few things that XML makes simple is to tell what is a tag
> > and what is text.
>
> That unfortunately isn't always respected, as I recently learned.  But
> that's a tooling issue that is easily rectified.
>
> --
> Tools-arch mailing list
> Tools-arch@ietf.org
> https://www.ietf.org/mailman/listinfo/tools-arch
>

--0000000000000c121a05ae569bd8
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr">should we consider in this conversation existing IDEs/edit=
ors people=C2=A0may use to create these artifacts? it seems to me that Mark=
down editors are far more on the rise than XML and that would be part of th=
e equation for someone about to start a document.=C2=A0<br clear=3D"all"><d=
iv><div dir=3D"ltr" class=3D"gmail_signature" data-smartmail=3D"gmail_signa=
ture"><br>- SB</div></div><br></div><br><div class=3D"gmail_quote"><div dir=
=3D"ltr" class=3D"gmail_attr">On Tue, Sep 1, 2020 at 8:57 PM Martin Thomson=
 &lt;<a href=3D"mailto:mt@lowentropy.net">mt@lowentropy.net</a>&gt; wrote:<=
br></div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8e=
x;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
<br>
On Wed, Sep 2, 2020, at 12:36, John Levine wrote:<br>
&gt; I think we underestimated how hard it is to do automated typsetting<br=
>
&gt; that produces good looking results so we ended up with a whole lot of<=
br>
&gt; very complex tagging to let people say in great detail how they want<b=
r>
&gt; things to look. We also put in a lot of semantic tags, e.g., this is a=
<br>
&gt; picture, that is sourcecode, this other thing is someone&#39;s name, w=
hich<br>
&gt; may be useful for future automated processing but we don&#39;t know ye=
t.<br>
<br>
I guess what I&#39;m challenging here is the inherent value of those annota=
tions.<br>
<br>
For the typesetting stuff, as that is tied to a very specific instance, att=
empting to preserve those as text is subsequently changed might be counterp=
roductive.<br>
<br>
For the semantic stuff, as they are not the product of any negotiation/cons=
ensus process, it is unlikely that they have any special status.=C2=A0 As s=
uch, I suggest that they exist on much the same level as other unofficial m=
arkings.=C2=A0 Useful or not, they aren&#39;t representative of the artifac=
t we are looking to preserve.=C2=A0 They are only useful to the extent that=
 they allow us to better communicate about that artifact, to which you next=
 point might be the most salient in this regard...<br>
<br>
&gt; One of the few things that XML makes simple is to tell what is a tag<b=
r>
&gt; and what is text.<br>
<br>
That unfortunately isn&#39;t always respected, as I recently learned.=C2=A0=
 But that&#39;s a tooling issue that is easily rectified.<br>
<br>
-- <br>
Tools-arch mailing list<br>
<a href=3D"mailto:Tools-arch@ietf.org" target=3D"_blank">Tools-arch@ietf.or=
g</a><br>
<a href=3D"https://www.ietf.org/mailman/listinfo/tools-arch" rel=3D"norefer=
rer" target=3D"_blank">https://www.ietf.org/mailman/listinfo/tools-arch</a>=
<br>
</blockquote></div>

--0000000000000c121a05ae569bd8--


From nobody Wed Sep  2 16:39:29 2020
Return-Path: <mt@lowentropy.net>
X-Original-To: tools-arch@ietfa.amsl.com
Delivered-To: tools-arch@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 697AD3A0808 for <tools-arch@ietfa.amsl.com>; Wed,  2 Sep 2020 16:39:27 -0700 (PDT)
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, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=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=lowentropy.net header.b=ooperktC; dkim=pass (2048-bit key) header.d=messagingengine.com header.b=B5OJhUWy
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 B4FlICKIZnqU for <tools-arch@ietfa.amsl.com>; Wed,  2 Sep 2020 16:39:26 -0700 (PDT)
Received: from out4-smtp.messagingengine.com (out4-smtp.messagingengine.com [66.111.4.28]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 4C9A63A0803 for <tools-arch@ietf.org>; Wed,  2 Sep 2020 16:39:26 -0700 (PDT)
Received: from compute2.internal (compute2.nyi.internal [10.202.2.42]) by mailout.nyi.internal (Postfix) with ESMTP id A34415C01DE; Wed,  2 Sep 2020 19:39:25 -0400 (EDT)
Received: from imap10 ([10.202.2.60]) by compute2.internal (MEProxy); Wed, 02 Sep 2020 19:39:25 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lowentropy.net; h=mime-version:message-id:in-reply-to:references:date:from:to :cc:subject:content-type; s=fm3; bh=8i7VIY0yFmPKSGALCAR1+KUeRD4H k6oL5GTKou0GMgs=; b=ooperktCIAoOkRB4T0xFKL/B7nUG6tgRukQrqm1wU5qm /GGQxNHNFKlAow9xDWbELwa5J0qzYX/EKHqwniPmiYCNQsWG30f7GdA18vGGWppI SQOheSNUhKP0DrCUODAbOmPzBIPi84p/ruLDTPoTWIeZ70DssvznI82hWDzBNxzu sK3+tvKm3wdp17zyd/8n/uY9TMjba/6LovgOuPGWKsdy+kv9PGrK3+OV4nt1f6qZ GdyrOrd+3gzVIYmyHptgqJ85NoG53ureBveyzFwFWRa52JnZIwEAWZ0gWFnudLO7 TO8C8sAnTR7cmrOCilROMkmcsPUs4BFyLtF03QyapA==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm3; bh=8i7VIY 0yFmPKSGALCAR1+KUeRD4Hk6oL5GTKou0GMgs=; b=B5OJhUWywQWKWJDRXSlznv LQENU1m8oK3FXsTE1/i/gWeJTK9CWimXXkbdzwLQ+BcaAEOo5T7g6TVZrZVlcolT KtbmR0StHyOarxkpdtdhhtAcmy7qboXIT+cWbahY8Qp62c3eNGOcUlSIc4UBRYIb 2R8/H8QBL7xYJcOpPn0uRxZ4Yko5b+Z1zWWPbv3wnxV5zIGk2kGG6WPqCA0Q/2lx kHGGZ5XjbZ91Fem+4sz0+rzNKPPKftUzl7fAKuW36zwupjB5N2yDRhLKGiBG0dYV VMt15ArHfjh79fL9C8R/j5c99VBPU8K77kJcNBzZb3KUdHsiladcLX4HPos6ywfw ==
X-ME-Sender: <xms:LC1QX_RK0ZAfPIjojC6mV8YrjmWqN9F3Ig4KSZB2M5CeF2YtWVdvGg> <xme:LC1QXww-Wqsqz_o9NiAspFVVfFxP7Vs2a5PQrMVBRpM9P0lg_0YyC80LlF7FtL5q2 NaDAk01mxOPTw2D6fw>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduiedrudegtddgvdefucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhepofgfggfkjghffffhvffutgesthdtredtreertdenucfhrhhomhepfdforghr thhinhcuvfhhohhmshhonhdfuceomhhtsehlohifvghnthhrohhphidrnhgvtheqnecugg ftrfgrthhtvghrnhepkeetueeikedtkeelfeekvefhkeffvedvvefgkefgleeugfdvjeej geffieegtdejnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrh homhepmhhtsehlohifvghnthhrohhphidrnhgvth
X-ME-Proxy: <xmx:LC1QX02Lm5t3PfRzuq_hLy32jj4RhWoiliMvs2cF1Mx0eJ3yl1h-Fw> <xmx:LC1QX_DpQHYF9of8Xw3iwXFlPuz4ufJaaV5B9DQ39QCGn4JcNZOPwA> <xmx:LC1QX4j_VLEg3Px7uagqFPxstH8ayA3CWgUOhsgjLaWf_9PzdR4TrQ> <xmx:LS1QXwLl_8fB2k-GDvWrqJw3ZYMi-2cMAMTV4y7IqAnBkVqm8YverA>
Received: by mailuser.nyi.internal (Postfix, from userid 501) id CD01520064; Wed,  2 Sep 2020 19:39:24 -0400 (EDT)
X-Mailer: MessagingEngine.com Webmail Interface
User-Agent: Cyrus-JMAP/3.3.0-248-gcd102cb-fm-20200901.001-gcd102cb9
Mime-Version: 1.0
Message-Id: <7ce017a4-e0aa-40b9-b9b7-05489f5a1141@www.fastmail.com>
In-Reply-To: <CA+tzEMB8Qj=b2dg-QoMtze7zWvHraxsAp=bGR-itEi_fU+Ly2A@mail.gmail.com>
References: <20200902023617.66BA41F5F442@ary.qy> <88deacab-2966-4a7f-a28f-b7c19abe3a2f@www.fastmail.com> <CA+tzEMB8Qj=b2dg-QoMtze7zWvHraxsAp=bGR-itEi_fU+Ly2A@mail.gmail.com>
Date: Thu, 03 Sep 2020 09:39:05 +1000
From: "Martin Thomson" <mt@lowentropy.net>
To: "Silvia Botros" <silviamikhail@gmail.com>
Cc: "John R Levine" <johnl@taugh.com>, tools-arch@ietf.org
Content-Type: text/plain
Archived-At: <https://mailarchive.ietf.org/arch/msg/tools-arch/iXKe89lFe6-GRLVt0-wbUpo6M88>
Subject: [Tools-arch] First-time contributions
X-BeenThere: tools-arch@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Tools Architecture and Strategy Team  <tools-arch.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/tools-arch/>
List-Post: <mailto:tools-arch@ietf.org>
List-Help: <mailto:tools-arch-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 02 Sep 2020 23:39:27 -0000

On Thu, Sep 3, 2020, at 01:51, Silvia Botros wrote:
> should we consider in this conversation existing IDEs/editors people 
> may use to create these artifacts? it seems to me that Markdown editors 
> are far more on the rise than XML and that would be part of the 
> equation for someone about to start a document. 

I think that is part of it for sure.  I think that balancing angle brackets tends to lead to XML-based editing being cumbersome.  But that makes me think more about the overall flow.

The main thing I concern myself with is the cycle of operations required for the first contribution.

If someone is familiar with email, you read a draft, find a nit, copy the relevant paragraph and section number, open a mail client, paste them in, add some comments, find the right email address, join the mailing list, send the email.

If someone is familiar with the github flow, you read a draft, find a nit, find the repository, fork the repository, clone the repository, setup remotes, make a branch, edit the document, make a commit with comments, push to your fork, open a pull request.  Maybe you also open issue instead, which is slightly easier (this is more common).

These are both high-friction processes.  So those who contribute are usually fairly well invested [1].  Right now, the only things we do to help are ad-hoc.  We sometimes put text near the front of a document that explains how to find the mailing list or repository.  We can almost certainly do better.

[1] The number of drive-by contributions on GitHub is non-trivial, which is - I believe - a positive artifact of the culture that has arisen there.


From nobody Wed Sep  2 17:28:20 2020
Return-Path: <mnot@mnot.net>
X-Original-To: tools-arch@ietfa.amsl.com
Delivered-To: tools-arch@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id E60413A08B8 for <tools-arch@ietfa.amsl.com>; Wed,  2 Sep 2020 17:28:19 -0700 (PDT)
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, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=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=mnot.net header.b=XeweV5b4; dkim=pass (2048-bit key) header.d=messagingengine.com header.b=HffxC5BZ
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 nG-eOIllODI5 for <tools-arch@ietfa.amsl.com>; Wed,  2 Sep 2020 17:28:18 -0700 (PDT)
Received: from out4-smtp.messagingengine.com (out4-smtp.messagingengine.com [66.111.4.28]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 247073A0878 for <tools-arch@ietf.org>; Wed,  2 Sep 2020 17:28:17 -0700 (PDT)
Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailout.nyi.internal (Postfix) with ESMTP id 526CB5C0180; Wed,  2 Sep 2020 20:28:16 -0400 (EDT)
Received: from mailfrontend2 ([10.202.2.163]) by compute4.internal (MEProxy); Wed, 02 Sep 2020 20:28:16 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mnot.net; h= content-type:mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; s=fm3; bh=V 5mQgZIDWQdNwzXMJJi+cbX1SMTh+yKWjLqu2AbM4XE=; b=XeweV5b4IAO6C9KoV JxcvjVYLr0u9WzPqvyi6+fRmrSk//+jPE3pA5zyKcJ8sMKhsYpuq2w+GM+TDuul5 BDqVVZYtMD9A1R3Y4nvk5XKj7oRssoVwg9LOIkhyLRiJn3thHD1FFPAf3EjLTTfb M2Q/lwqGfEOeclVHTxHKHO9DznkCPHlNQXDAHDpT1+YOMXe+JWk/eNzzRqfP2+6U NYcIs1qMSN4Je1Uri0dZ/Le/kvURQyQq0dDYtEZeQTwlxhfLQftU91ie2d56sAdH P0rFFRA+whiC6UN5a4y/yxy5QSi6OjdYwQNrFGkxRsca8BwpIkR+/lSfmOBC8uEb zvvFA==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm3; bh=V5mQgZIDWQdNwzXMJJi+cbX1SMTh+yKWjLqu2AbM4 XE=; b=HffxC5BZQ+m8eLlNRrCHhnq+LIUYumOIOp0V3QJmzuK5oF/ePlkosaXNV t+qScaYrlHEtT7shdQKK68YU/O+qgZM8P7ylbQdabtEpKp2BlHZrCAhpvfwC8qGK 3i+KXovvMFUJKHtLwPSaD8m6Nbw1BkUgpM5ZSOFqAHQPmvFi1OM0jJjzWrSGPDCI fB5YAg+sqU2tHHjj/E1by70Z8OR6J1wxiTFXmyklYZOt9H1e+xgib939LSU0EcFZ X+UMmCuKqRLl+3BMWzefm+Z1D967+F0GoceayC+ViSpR2q+mC1jiKRSiKw6UMVH6 x5Ry3foNakPdOepA05IIPYkwxO4Vw==
X-ME-Sender: <xms:nzhQXynFvWW8zpUd-N37lOmQo4X1Gik2bxcDZNL_A7_yRbRHTRxxvw> <xme:nzhQX53ksWgq2T-qd6dj5vagHZKhIL6IP75tZoyYd_HqlouVg2kP62en5nMjDR9zr arBXWRG1ORAKT2qUw>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduiedrudegtddgfeefucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurheptggguffhjgffgffkfhfvofesthhqmhdthhdtvdenucfhrhhomhepofgrrhhk ucfpohhtthhinhhghhgrmhcuoehmnhhothesmhhnohhtrdhnvghtqeenucggtffrrghtth gvrhhnpeevffffhfduteevvefhueffieegtdeutdehffeltefffedttdeggeejheeiueet teenucffohhmrghinhepmhhnohhtrdhnvghtnecukfhppeduudelrddujedrudehkedrvd ehudenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehm nhhothesmhhnohhtrdhnvght
X-ME-Proxy: <xmx:nzhQXwq9P0UrSCnv0Fl2UrmDSeIStR1nWKiECUmWuvSaMl33mIiHoQ> <xmx:nzhQX2nlFfZfDf_Cyn8XFXd4RHivwlcEhm6sIJtodDONC17IDrwhmw> <xmx:nzhQXw3Ifjp7PRD8Rw-BTpAPIptzOurEIvquhm4ZG_RBO5tNhXnr_g> <xmx:oDhQXzS-_WxF-hpsolVF3-9qR4IcHnt01xbxElDIb0QDlfulFZBlOw>
Received: from [192.168.7.30] (119-17-158-251.77119e.mel.static.aussiebb.net [119.17.158.251]) by mail.messagingengine.com (Postfix) with ESMTPA id 9F15130600A3; Wed,  2 Sep 2020 20:28:14 -0400 (EDT)
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.80.23.2.2\))
From: Mark Nottingham <mnot@mnot.net>
In-Reply-To: <7ce017a4-e0aa-40b9-b9b7-05489f5a1141@www.fastmail.com>
Date: Thu, 3 Sep 2020 10:28:11 +1000
Cc: Silvia Botros <silviamikhail@gmail.com>, tools-arch@ietf.org, John R Levine <johnl@taugh.com>
Content-Transfer-Encoding: quoted-printable
Message-Id: <6F579927-EA73-48F1-BB85-1A56AAB627C8@mnot.net>
References: <20200902023617.66BA41F5F442@ary.qy> <88deacab-2966-4a7f-a28f-b7c19abe3a2f@www.fastmail.com> <CA+tzEMB8Qj=b2dg-QoMtze7zWvHraxsAp=bGR-itEi_fU+Ly2A@mail.gmail.com> <7ce017a4-e0aa-40b9-b9b7-05489f5a1141@www.fastmail.com>
To: Martin Thomson <mt@lowentropy.net>
X-Mailer: Apple Mail (2.3608.80.23.2.2)
Archived-At: <https://mailarchive.ietf.org/arch/msg/tools-arch/vGbPa2Zj4e5wakbusz-sK6w3RcE>
Subject: Re: [Tools-arch] First-time contributions
X-BeenThere: tools-arch@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Tools Architecture and Strategy Team  <tools-arch.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/tools-arch/>
List-Post: <mailto:tools-arch@ietf.org>
List-Help: <mailto:tools-arch-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/tools-arch>, <mailto:tools-arch-request@ietf.org?subject=subscribe>
X-List-Received-Date: Thu, 03 Sep 2020 00:28:20 -0000

> On 3 Sep 2020, at 9:39 am, Martin Thomson <mt@lowentropy.net> wrote:
>=20
> If someone is familiar with the github flow, you read a draft, find a =
nit, find the repository, fork the repository, clone the repository, =
setup remotes, make a branch, edit the document, make a commit with =
comments, push to your fork, open a pull request.  Maybe you also open =
issue instead, which is slightly easier (this is more common).

If someone is familiar with the GitHub flow, they'd read the draft, find =
a nit, go the draft's page, click 'Edit this file' (the pencil icon), =
make the change, and then click 'Propose changes'.

This is pretty low-friction, once you know it's there.

Cheers,

--
Mark Nottingham   https://www.mnot.net/