Clarify and simplify the sections regarding publication and process 2021
@plehegar is already working on this.
Since Sep 27, 2023.
- 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).
- 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.
- 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).
- Create new visualizations for both pathways
- Clarify the types of changes (the levels system is actually quite clear, I think it just needs more prominence).
- Clarify revision process for older specifications that are not on the new process.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.