Subject: [rfc-i] Proposed survey on I-D authoring tools

From: Jay Daley <[email-masked]>
Date: Wed, 30 Sep 2020 15:58:43 +1300

We are planning to send out a survey on I-D authoring tools to authors and wider to provide information for a number of groups including RSOC, Tools Team, Tools Architecture and Strategy Team, and the LLC.  The proposed question plan is below and we would welcome any feedback.  In particular:

- are all the important questions asked?
- are all the key tools / processes mentioned?
- is the language clear including for those for whom English is not their first language?

thanks in advance
Jay

# Question Plan

[PAGE] 
Introduction

[HELPTEXT]
Thank you for taking part in this survey.  This survey has been sent to everyone who has authored an Internet-Draft (I-D) in the last five years and is open to anyone who has ever authored an I-D.

We are hoping to understand what formats and tools you use to author I-Ds, from drafting to submission.

In particular, we are hoping to find out more about the use (or non-use) of the v3 XML format for I-Ds, which became the publication format for RFCs on 16 September 2019.

[QUESTION - Multiple Choice]
Approximately, how many I-Ds have you authored in total (different I-Ds not versions of the same I-D)?
If you need a reminder then your Datatracker page will have the details. 
	• 0
	• 1-5
	• 6-10
	• 11-20
	• 21-50
	• 51+

[QUESTION - Matrix/Rating Scale]
Approximately, how many times have you submitted a draft (both a new draft and a new version) to the Datatracker?
Items
	• 0
	• 1-10
	• 11-20
	• 21-50
	• 50-100
	• 101+
Scale
	• In total
	• Last 2 years (Since September 2018)
	• Last year (since September 2019)

[QUESTION - Multiple Choice]
How many RFCs have you authored?
	• 0
	• 1-5
	• 6-10
	• 11-20
	• 21-50
	• 51+

[PAGE]
Drafting to submission

[LOGIC]
Only get here if they have authored an I-D.

[QUESTION - Matrix/Rating Scale]
How often have you used the following document format(s) and associated output process(es) (editor/template/converter) when authoring an I-D? (Ignore any you don’t know about)
Items
	• Plain text using no markup
	• Plain text using a different output process
	• Markdown using the kramdown-rfc2629 converter
	• Markdown using the mmark converter
	• Markdown using the draftr converter
	• Markdown using the Pandoc2rfc converter
	• Markdown using a different output process
	• XML using the XMLMind editor and xml2rfc-xxe
	• XML using a different output process
	• AsciiDoc using the metanorma-ietf (formerly known as asciidoctor-rfc) converter
	• AsciiDoc using a different output process
	• TeX / LaTeX using Lyx editor and lyx2rfc
	• TeX / LaTeX using a different output process
	• nroff using the Nroff Edit editor
	• nroff using nroff2xml template
	• nroff using a different output process
	• Microsoft Word rich text using Joe Touch’s Word Template (RFC5385)
	• Microsoft Word rich text using a different output process (This means specifically using rich text styles that a template/convertor will recognise, it does not mean using this an editor for one of the other formats)
	• Other format (Only use this option if you author in a different format to all of those above) [PLEASE SPECIFY what format you author in and what output process you use]
Scale
	• Always
	• Very often
	• Sometimes
	• Rarely
	• Never [Ensure this is scored as 0]

[QUESTION - Comment Box]
If you answered “a different output process” in the question above then please specify what it is?

[QUESTION - Checkboxes]
How did you choose the document format(s) and associated output process(es) that you use? (Check all that apply)
	• I researched the tools
	• I decided on my authoring format first and then chose a tool that uses that
	• I saw a presentation on one of the tools at an IETF meeting
	• Another author chose for me
	• The I-D I wanted to contribute to was already drafted in one of these tools
	• Other [PLEASE SPECIFY]

[QUESTION - Matrix/Rating Scale]
How often have you used the following template(s) when drafting an I-D? (Ignore any you don’t know about)
Items
	• A copy of a previous I-D / RFC
	• A template from https://tools.ietf.org/tools/templates/ 
	• A template that came with my chosen authoring tool/process
	• My own
	• Other [PLEASE SPECIFY]
Scale
	• Always
	• Very often
	• Sometimes
	• Rarely
	• Never [Ensure this is scored as 0]

[QUESTION - Matrix/Rating Scale]
How often have you used the following additional authoring tools? (Ignore any you don’t know about)
Items
	• bibtext2rfc to convert bibtext citations into bibxml references
	• bibxml2md to convert bibxml references into markdown
	• Doublespace tool to change spacing between sentences to two spaces
	• id2xml to convert a plain text I-D into XML
	• idnits to check a draft before submission 
	• idspell to check a draft for spelling errors
	• rfc2629xslt to convert RFC XML into another output format
	• RFC dependency checker
	• rfcdiff to find diffs between versions of drafts
	• svgcheck to check a draft for SVG schema compliance 
	• xml2rfc validator to validate RFC XML
Scale
	• Always
	• Very often
	• Sometimes
	• Rarely
	• Never [Ensure this is scored as 0]

[QUESTION - Checkboxes]
How do you run your tools? (Check all that apply)
	• Locally
	• On a private hosted server
	• On an IETF public web service
	• On a third-party public web service 
	• Using CI/CD with GitHub
	• Using CI/CD with Gitlab
	• Other [PLEASE SPECIFY]

[PAGE]
XML v3

[QUESTION - Multiple Choice]
How do you rate your knowledge of the v3 official RFC/I-D XML format?
	• Excellent
	• Good
	• Fair
	• Poor
	• None

[QUESTION - Matrix/Rating Scale]
How satisfied are you with the following characteristics of the v3 XML format?
Items
	• Ease of use
	• Features
	• Documentation
	• Tools support
	• Other [PLEASE SPECIFY]
Scale
	• Very satisfied
	• Satisfied
	• Neutral
	• Dissatisfied
	• Very dissatisfied
	• N/A

[QUESTION - Matrix/Rating Scale]
How important are the following characteristics of the v3 XML format to you?
Items
	• Ease of use
	• Features
	• Documentation
	• Tools support
	• Other [PLEASE SPECIFY]
Scale
	• Very important
	• Important
	• Neutral
	• Unimportant
	• Very unimportant
	• N/A

[QUESTION - Comment Box]
What more needs to be done to support the rollout of the v3 XML format?

[PAGE]
State of the current authoring tools landscape

[QUESTION - Matrix/Rating Scale]
How satisfied are you with the following characteristics of authoring tools?
Items
	• Ease of use
	• Integration with IETF processes
	• Support for the full range of tags / metadata
	• Control of output
	• Support of various output formats
	• Speed at which new features are added
	• Overall quality
	• Choice of different tools
	• Other [PLEASE SPECIFY]
Scale
	• Very satisfied
	• Satisfied
	• Neutral
	• Dissatisfied
	• Very dissatisfied
	• N/A

[QUESTION - Matrix/Rating Scale]
How Important are the following characteristics of authoring tools to you?
Items
	• Ease of use
	• Integration with IETF processes
	• Support for the full range of tags / metadata
	• Control of output
	• Support of various output formats
	• Speed at which new features are added
	• Overall quality
	• Choice of different tools
	• Other [PLEASE SPECIFY]
Scale
	• Very important
	• Important
	• Neutral
	• Not important
	• Not at all important
	• N/A

[QUESTION - Multiple Choice]
Should the IETF invest in a new, modern toolchain for authoring drafts?
	• Strongly agree
	• Agree
	• Neutral
	• Disagree
	• Strongly disagree

[QUESTION - Matrix/Rating Scale]
How important is it for you for any new tool to support the following authoring formats? 
Items
	• Markdown
	• XML
	• WYSIWYG
	• Other [PLEASE SPECIFY]
Scale
	• Very important
	• Important
	• Neutral
	• Not important
	• Not at all important
	• N/A

[QUESTION - Comment Box]
Do you have any more feedback on authoring tools and formats?

-- 
Jay Daley
IETF Executive Director
[email-masked]

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Randy Bush <[email-masked]>
Date: Wed, 30 Sep 2020 16:07:43 -0700

> If you need a reminder then your Datatracker page will have the

not obvious how for not-a-datatracker-geek.  give instructions, please

> Approximately, how many times have you submitted a draft (both a new draft and a new version) to the Datatracker?

hard to answer

> 	• Other format (Only use this option if you author in a
> different format to all of those above) [PLEASE SPECIFY what format
> you author in and what output process you use]

uh, where is xml using a classic ascii text editor, e.g. emacs, and xml2rfc?

randy

---

From: Jay Daley <[email-masked]>
Date: Thu, 1 Oct 2020 12:19:26 +1300

> On 1/10/2020, at 12:07 PM, Randy Bush <[email-masked]> wrote:
> 

Yes, not easy is it.  I’ve asked for help.  (for info my page is at https://datatracker.ietf.org/person/Jay%20Daley but I don’t know how to navigate to that).

>> Approximately, how many times have you submitted a draft (both a new draft and a new version) to the Datatracker?

Yep, hence the suggestion to look on your Datatracker page.

> uh, where is xml using a classic ascii text editor, e.g. emacs, and xml2rfc?

That would be "• XML using a different output process" but in response to someone else I’ve already added

	"XML using xml2rfc to create plain text for submission"

Does that match your usage of xml2rfc?

Jay

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Randy Bush <[email-masked]>
Date: Wed, 30 Sep 2020 16:24:17 -0700

> Yep, hence the suggestion to look on your Datatracker page.

that would be expecting a lot from datatracker.  but i wait to learn

> Does that match your usage of xml2rfc?

yes, but many of your other options have the attribute of what kind of
editor.  hence my saying "ascii editor and xml2rfc" which kinda assumes
that i edited xml.

randy

---

From: Jay Daley <[email-masked]>
Date: Thu, 1 Oct 2020 12:31:38 +1300

> On 1/10/2020, at 12:24 PM, Randy Bush <[email-masked]> wrote:
> 

I’ve only mentioned an editor where it has specific functionality (either in-built or via a plugin) to support I-D authoring.

I don’t think it adds anything for us to find out if someone wrote the XML in one of 100+ XML editors or 10000+ text editors.  Do you agree?

Jay

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Dan York <[email-masked]>
Date: Thu, 1 Oct 2020 01:08:26 +0000

Jay,
A couple of comments inline… 

> On Sep 29, 2020, at 10:58 PM, Jay Daley <[email-masked]> wrote:
> 
> [QUESTION - Checkboxes]

For clarity, perhaps “Another author of my document chose for me”

> 	• The I-D I wanted to contribute to was already drafted in one of these tools

What about something like “Someone else helped me set up my tools”?  I know I’ve helped a couple of people get set up by explaining what I use and pointing people to tools.  You could think of that as “I researched my tools” … but it might be interesting to know how much is really being passed around by people sharing info with each other.

> XML v3

This entire section below assumes you either author in XML or have sufficient complexity in your documents where you need to know about XMLv3. In recent years I’ve shifted to writing drafts entirely in Markdown, and to be honest all my drafts have been simple enough in their text and formatting that I haven’t needed to know anything about the underlying XML. The transition from XML v2 to v3 did not seem to make a difference for my documents.

I think there are probably some % of authors who are in the same situation. Particularly newer authors who did not come out of the XML world and do their editing in some text format like Markdown or AsciiDoc, or use MS Word.

I understand the need to ask these questions because there *are* authors who do care about the v3 format (and in some cases care very strongly).

Maybe to make it easier on survey respondents, if you are using SurveyMonkey or some similar tool, perhaps you can use the option to conditionally display questions so that if someone answers “None” on the knowledge of the v3 format, then they won’t see the additional questions.

> State of the current authoring tools landscape

On these two questions below, do we want to include something about “Integration with version control systems”?  I’m thinking about some of the different tools that are designed to work with git / GitHub.

> 	• Choice of different tools

Regards,
Dan

---

From: Randy Bush <[email-masked]>
Date: Wed, 30 Sep 2020 18:27:23 -0700

> I’ve only mentioned an editor where it has specific functionality
> (either in-built or via a plugin) to support I-D authoring.

i guess you have never met emacs' xml mode

randy

---

From: Jay Daley <[email-masked]>
Date: Thu, 1 Oct 2020 14:39:22 +1300

> On 1/10/2020, at 2:27 PM, Randy Bush <[email-masked]> wrote:
> 

I wouldn’t describe that as specific functionality to support I-D authoring.  An example of the what I mean is the xml2rfc-xxe plugin to XMLMind, which is maintained by some IETF volunteers.

I’m not sure we get anywhere by asking people if they prefer vi or emacs.

Jay

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Jay Daley <[email-masked]>
Date: Thu, 1 Oct 2020 14:44:21 +1300

Thanks Dan

> On 1/10/2020, at 2:08 PM, Dan York <[email-masked]> wrote:
> 
> Jay,

That and the suggestion above are both good, thanks.

> Maybe to make it easier on survey respondents, if you are using SurveyMonkey or some similar tool, perhaps you can use the option to conditionally display questions so that if someone answers “None…

My plan was to make those optional rather than use the logic but I will look at that again when I get to testing the survey flow.

> On these two questions below, do we want to include something about “Integration with version control systems”?  I’m thinking about some of the different tools that are designed to work with git /…

Yes I will add that.

thanks
Jay

-- 
Jay Daley
IETF Executive Director
[email-masked]