w3c / w3c/process

Clarify and simplify the sections regarding publication and process 2021

Open
#700 13 comments 3 reactions 2 assignees View on GitHub

@plehegar is already working on this.

Since Sep 27, 2023.

Topic: Simplifications
Dominant language
HTML
Stars
262
Forks
194
PR merge metrics
No merged PRs in 30d

Description

I am aware that previous issues have been opened regarding this (#589, #590), but I want to further expand and discuss the possibility of completely revising this section for readability.

Background: EPUB 3 WG is planning to vote this week to move the specification to PR. As part of this, we need to make the decision as to whether we want to make EPUB3 a "living standard" in the common parlance. To support my WG, I sent an email explaining what the difference is, but to make sure I was being accurate, I decided to do a close read of most of section 6, but specifically 6.3.

I cannot emphasize this enough, I am a native english speaker with a degree in English Literature and 5+ years of experience in standards including as an editor: this section is almost completely impossible to understand. I say almost because I was able to write my summary for the working group, as to whether it's helped anyone in making a decision, I have no idea.

I am not saying this to criticize anyone, but I do think we need to look at the following issues within the text and revise according. I am willing to help with this (I joined process CG so I'm on the hook).

  1. Address the terminology issues raised in issue #590 - Manu provided an excellent simplification of the terminology to start from, and I had the same experience with confusion over the terminology.
  2. Clarify that there are 2 paths a new specification can take, and give proper naming to those (none of this "accepts new features" terminology, it's not a name).
  3. Create new visualizations for both pathways
  4. Clarify the types of changes (the levels system is actually quite clear, I think it just needs more prominence).
  5. Clarify revision process for older specifications that are not on the new process.
  6. Remove the circular references, many sections link back to each other and give the illusion of clarifying while somehow making things more confusing (related to #590).

Chairs and editors for new specifications need to be able to explain this to their WGs and implement these changes, right now it's basically impossible.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.