Markdown Version | Session Recording

Session Date/Time: 17 Sep 2025 14:00

EODIR

Summary

The EODIR session focused on brainstorming usability issues with GitHub in the IETF context and identifying gaps in current guidance. Key discussions revolved around defining different IETF GitHub user audiences, the scope of initial guidance (focusing on the web UI and specific tooling), and establishing concrete, actionable steps to improve the experience for working group chairs, authors, and reviewers. Three specific wiki content pieces were proposed as immediate action items, aiming to provide concise, practical guidance.

Key Discussion Points

• Locating Meeting Resources: An initial point of discussion highlighted persistent usability challenges with the Datatracker for finding interim meeting note pages, suggesting a broader issue for the tools team.
• Meeting Purpose: The primary goal was to brainstorm usability issues with GitHub for the IETF community, identify gaps in existing helper information, and explore potential improvements, acknowledging varying levels of GitHub proficiency within the community. The "Note Well" applied to the session.
• Defining GitHub Audiences: Participants identified several distinct user categories based on their role and GitHub experience:
  • Experienced Developers: Those using Git/GitHub regularly in their day jobs, familiar with concepts like pull requests.
  • Tooling Users: Individuals using IETF-specific tools like Martin Thompson's xml2rfc templates, who may not be traditional coders but leverage Git.
  • "Drive-by" Contributors: GitHub-familiar users making occasional contributions (e.g., pull requests, suggesting changes).
  • Newcomers: Individuals unfamiliar with GitHub, looking to make minor edits or clarifications.
  • Leadership (WG Chairs/ISG): Responsible for setting up and managing working group repositories/organizations, distinct from individual document contributions.
  • Reviewers: Divided into IETF veterans (potentially non-GitHub users preferring email diffs) and GitHub-native developers.
• Role vs. Expertise: A discussion arose about whether to categorize users by their IETF role or their GitHub experience. There was a strong recommendation to focus on GitHub experience and the specific tasks users need to accomplish.
• Scope of Guidance: To simplify the initial problem set, there was a strong recommendation to focus new guidance on:
  • The GitHub web UI (github.com in a browser).
  • The use of Martin Thompson's tooling/templates for internet drafts (e.g., cramdown-rfc).
  • Explicitly not focusing on the command-line interface (CLI) for initial onboarding, as CLI users are typically more experienced.
• GitHub Workflows & Best Practices:
  • Working Group Organization Setup: While the Secretariat creates GitHub organizations, chairs are responsible for configuring them (e.g., descriptions, labels). Tools and guidance for this setup are needed.
  • Mailing List Integration: Discussed the importance of connecting GitHub activity to mailing lists. Existing tools can automate summaries of PRs and issues to mailing lists (e.g., weekly activity logs). Best practices are needed for chairs and authors on what constitutes important enough information to share on the list. RFC 8875 was cited as relevant to IETF rules for GitHub use.
  • "GitHub as Dropbox": Noted that some users treat GitHub as a simple file storage system (like Dropbox), which discourages proper Git workflow (e.g., XML file updates with hard-to-read diffs).
• XML to Markdown Conversion: The challenge of migrating existing XML drafts to Markdown for better GitHub diffs and PR workflows was raised. While desirable, a direct, public tool for XML-to-Markdown conversion for IETF drafts does not currently exist, making it a manual process. This was acknowledged as a potential future tool request for the tools team. cramdown-rfc (Karsten's Markdown flavor) was noted as the standard for IETF drafts.
• Existing Helper Information: RFCs, Martin Thompson's tutorials, and even generative AI (e.g., ChatGPT for debugging errors) were mentioned as current "helper" resources, but a need for more concise, targeted, and pictorial guidance was emphasized.
• Effective Training Approaches: A sense of those present indicated that previous broad tutorials (e.g., Martin's IETF123 presentation) were not as effective as desired. A strong recommendation emerged for:
  • Step-by-step wiki content: Concise, written guides with screenshots.
  • Workshop-style, hands-on training: Interactive sessions with partners, focused on mechanics and doing, rather than just watching. A hackathon table was suggested, but also a specific "Chairs Forum" special edition was brainstormed to reach the target audience effectively.

Decisions and Action Items

1. Consensus on Scope for Initial Guidance: Focus future guidance development on GitHub's web UI and Martin Thompson's tooling/templates. (Decision)
2. Develop Specific Wiki Content (Immediate Action Items): Create concise, step-by-step wiki content for the following three areas, aiming for first cuts by IETF 124:
   • Organizing Your Workspace (for WG Chairs): Guidance on configuring a working group's GitHub organization after it's created by the Secretariat.
     • Action: Rich and Cindy (Secretariat) to collaborate on this.
   • Using Martin Thompson's Tool and Web UI for Authoring (for Authors): Guidance on creating and managing drafts using the recommended tooling and GitHub web interface.
     • Action: Jean to lead, leveraging existing documentation and contributing updates.
   • Making a Pull Request (for Reviewers): Guidance on how to create and manage pull requests using the GitHub web UI.
     • Action: Jean to review if existing Martin Thompson documentation is sufficient or needs augmentation.
3. Coordination of Wiki Content Development:
   • Action: Greg to spin up initial wiki pages, Google Docs, or GitHub Markdown documents for these three content pieces and coordinate efforts.
4. Onboarding Email for WG Chairs: Explore the creation of a welcome/onboarding email for new and long-serving working group chairs, containing pointers to essential information, including GitHub guidance.
   • Action: To be bookmarked for future discussion, outside the immediate scope of GitHub content but recognized as a valuable improvement.

Next Steps

• Timeline: Aim for first drafts of the three identified wiki content pieces (Organizing Workspace, Authoring with Martin's Tool/UI, Making a Pull Request) by IETF 124.
• Call for Contributors: A question will be posted on the EODIR mailing list to solicit additional contributors for these content development efforts.
• Future Training Events: Brainstorm alternative venues for hands-on, workshop-style training (e.g., a special "Chairs Forum" session) that would be more effective for the target audience than a traditional hackathon.