Re: [rfc-i] The role of txt format in ietf document development

[Martin Thomson <[e-mail]>]

On Thu, Oct 29, 2020, at 09:41, Carsten Bormann wrote:
> Having embraced this move to humane markup in a number of markdown- and 
> asciidoc-based authoring formats for I-Ds and RFCs in the last decade, 
> I don’t think we will move away from that.  The main reason is that it 
> is really easy to collaborate on humane markup using tools like git and 
> github, and the IETF document generation process is fundamentally 
> collaborative, much more so than in other SDOs.

This I agree with.

However, I still find that people routinely refer to the rendered versions.  Many outside reviews refer to text by section numbers (which is not in the source, ouch).  For people working on QUIC, we've mostly moved to direct references to the editor's copy.  The addition of pilcrows on paragraphs has been a huge help in improving our ability to reference text.  I wish that we could teach more people to do that.

There's a gap there that I'm not completely comfortable with, but I believe that the fundamental direction here is broadly right.  That's why I too have been very happy with use of markdown as it broadly meets these goals.

Collaborating on a Word document is great when you have either a small, tightly-knit group who can use the tool effectively.  That is, when the online tools are used, which support commenting and suggestions.  But that process doesn't scale well and I don't see it as suitable in the working group setting.

I guess if you are comfortable with process that is slow and formal, and you can rely on extensive clerical support, the submission of a changeset in the form of a Word document is workable.  Or at least not the most urgent process problem you need to concentrate on.

> W3C is maybe an exception, and they have an amazing tool called respec 

There is also bikeshed, which I'm having trouble distinguishing from respec as the two evolve.  But your observation holds: they too create a text artifact that is the focus of collaboration.  They provide more features than I think are needed in this context, but they are still fundamentally an embodiment of the same principles: collaboration is what makes the work we do valuable.
_______________________________________________
rfc-interest mailing list
[e-mail]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest