Markdown Version | Session Recording
Session Date/Time: 25 Jun 2025 19:00
RPC
Summary
The RPC community call continued discussion on strategic transformations identified during an April retreat, focusing on enhancing transparency, adapting to changing author processes (including Markdown support), and modernizing version control. Key discussions included the need for clearer author visibility into document status, the complexities of supporting diverse authoring formats, and plans to introduce a new intake questionnaire for documents entering the queue. Decisions were made regarding transitioning to an open mailing list and adopting internal GitHub for version control. An update on current projects and team activities was provided, noting a significant increase in Q1 2023 document volume, which has led to longer processing times.
Key Discussion Points
-
Transparency Initiatives:
- The RPC aims to be sufficiently transparent to the IETF community, moving from opaque internal workings.
- Ongoing community calls and a public roadmap (linked in GitHub) are projects supporting this.
- Authors expressed a desire for better estimates on document publication timelines post-IESG review. The RPC confirmed that the new Queue Management System (QMS) will provide enhanced visibility and estimated timelines.
- Mailing List: The current private RFC-editor mailing list will be replaced by a new, open list to allow community perusal of archives and RPC interactions. This change is dependent on the rollout of the new QMS.
- Service Level Agreement (SLA): The current SLA (from 2016) is no longer fit for purpose due to increased workload from RFC XML v3 and document "burstiness." A project is underway to work with the community to define a new SLA, identifying what needs to be measured and target metrics. Discussions will continue on the RFC Interest List.
-
Evolving Authoring Processes:
- Markdown Support: The RPC is working towards supporting Markdown (specifically cramdown RFC) as an input format. Experiments have been run, and editors are undergoing training.
- Discussion on Markdown:
- While acknowledging its potential for ease of use, skepticism was expressed regarding Markdown's ability to express all necessary formatting and its suitability as a canonical format given XML's role.
- The RPC clarified that the primary goal of Markdown support is to enable authors to review RPC edits in Markdown at the beginning of the O48 state, facilitating easier diff review and backporting to personal GitHub repositories. This would result in a two-approval process during O48: Markdown edits, then final XML output. XML submission remains an option.
- Concerns were raised about potentially increasing the burden on authors by requiring familiarity with multiple formats (XML, Markdown, PDF, text, HTML) and the historical tension between author control over formatting and editorial consistency.
- A higher-level conversation about the nature of authoring and consistency of the RFC series was suggested to guide future technology development.
-
Modern Version Control (GitHub Integration):
- The RPC currently lacks a modern version control system.
- Internal Use: The RPC plans to adopt GitHub for internal use, with one document per repository, automated repository creation, and updated internal processes. This focuses on a modern version control system for RPC operations.
- Author Support: A future phase involves supporting authors by making it easier to backport RPC edits to their GitHub repositories, with Markdown support in O48 being a key enabler for this. This requires new tooling and GitHub Actions.
-
Project Updates (from previous community call):
- Intake Form: A questionnaire has been drafted and a process defined to gather information from authors when documents enter the queue, aiming to expedite the copy-editing process. It will be rolled out starting mid-July.
- Discussion centered on the timing of this questionnaire (after IESG approval, when authors feel "done") and the challenges of multi-author documents. The RPC is comfortable working with the first responding author.
- The optional nature of shepherd write-ups means they cannot be fully relied upon for all necessary information.
- Tools Team Progress: The Tools Team is actively developing the new QMS, a new RPC website, and new editing tools.
- Team Specialization: The RPC is defining qualifications for an editor with SVG expertise, as SVG usage is increasing, and currently, there is no in-house expert.
- "Not Ready" Documents: A process is being developed to quickly identify and return documents that are not ready for copy-editing to the stream.
- To-Do Items (Ongoing): Identifying RPC processes that could be shifted to authors (e.g., source code validation) and conducting a cost-benefit analysis of RFC XML features to manage complexity and workload.
- Intake Form: A questionnaire has been drafted and a process defined to gather information from authors when documents enter the queue, aiming to expedite the copy-editing process. It will be rolled out starting mid-July.
-
Operational Reports & Statistics:
- Individual editors provided updates on their current workload, documents in various stages (editing, O48, publication), and notable challenges encountered (e.g., language issues, ASCII/SVG mismatches, inconsistent terminology, link rot, complex Enroth formatting).
- A significant spike in pages and documents entered the queue in Q1 2023, pushing the RPC into "Tier 3" under the old SLA metrics. This has led to currently longer processing times. This spike was attributed to ADs clearing outgoing queues before the incoming AD transition.
- The public roadmap GitHub repository has been made fully public.
Decisions and Action Items
- Decision: A new, open RPC mailing list will be established, replacing the current private list. This is dependent on the rollout of the new Queue Management System.
- Decision: The RPC will adopt GitHub for internal modern version control, with one repository per document.
- Action Item: The RPC will roll out an author questionnaire for documents entering the queue, starting mid-July, to collect information that aids in the editing process.
- Action Item: The RPC will continue to work with the community to define a new Service Level Agreement (SLA) that better reflects current workload and processes.
- Action Item: The RPC will continue training editors on processing Markdown documents, specifically cramdown RFC.
- Action Item: The RPC will draft qualifications and a hiring process for an editor with SVG expertise to address increasing SVG usage in documents.
- Action Item: The RPC plans to provide more guidance to authors regarding SVG usage, particularly concerning its appearance in PDF output.
Next Steps
- Conversations regarding the new SLA definition will continue on the RFC Interest List.
- The RPC will continue to develop tooling for Markdown support and full GitHub integration for authors.
- Authors should expect to receive the new intake questionnaire when their documents enter the RPC queue from mid-July onwards.
- For those attending Madrid remotely, the RPC will explore options for virtual office hours (e.g., Zulip) to supplement in-person interaction at the RPC desk.
- The next RPC community call is planned for mid-August.