Clarify and simplify the sections regarding publication and process 2021

[wareid]

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.

[marcoscaceres]

@wareid, agree (also as someone with a BA specializing in semiotics and someone working on standards for ~15 years)... I tend to just drop sections of the Process into ChatGPT nowadays and ask it to explain it to me in plain English. It does a pretty good job :)

Half joking... maybe we should drop more of the Process into ChatGPT and get it to rewrite it into something more comprehensible.

[wareid]

Honestly I love that as a starting point to turn into something more readable. If there is something LLM’s do well, it’s summarization! I’d be happy to take a crack at in the form of a wiki for others to review?

Get Outlook for iOShttps://aka.ms/o0ukef

---

From: Marcos Cáceres @.> Sent: Thursday, June 29, 2023 11:16:41 PM To: w3c/w3process @.> Cc: Reid, Wendy @.>; Mention @.> Subject: Re: [w3c/w3process] Clarify and simplify the sections regarding publication and process 2021 (Issue #700)

[EXTERNAL] This message comes from an external organization.

@wareidhttps://github.com/wareid, agree (also as someone with a BA specializing in semiotics and someone working on standard for ~15 years)... I tend to just drop sections of the Process into ChatGPT nowadays and ask it to explain it to me in plain English. It does a pretty good job :)

Half joking... maybe we should drop more of the process into ChatGPT and get it to rewrite it into something more comprehensible.

— Reply to this email directly, view it on GitHubhttps://github.com/w3c/w3process/issues/700#issuecomment-1614058038, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AB5NDKLZ2KV3RMZUJ4IYVHDXNZAJTANCNFSM6AAAAAAUEEIJ4I. You are receiving this because you were mentioned.Message ID: @.***>

[nigelmegitt]

I think it's fine to try this out and see what it comes up with, but I'd sound a strong note of caution: given how much time and brain power has been spent, mainly by the Editors, getting the words of the Process to say what we intend them to mean, I'd be very wary of a good sounding and maybe more readable version having unintended substantive changes.

[TzviyaSiegman]

Let's consider https://hemingwayapp.com/, which is geared toward readability instead of summarization. This is often used to ensure cognitive accessibility.

[dwsinger]

There has been quite a lot of effort on re-organizing and limited re-writing over the last few years; we realized that the document had grown in an organic way and needed serious attention. I don't want to suggest that we're done, in any way.

Putting it through readability analysis is a great idea.

The caution is, of course, the usual rule (that applies in software too): if it works, leave it alone. If you edit, you may (actually, will) introduce bugs. But unreadability is also a bug.

[frivoal]

@wareid I agree with you that these specific sections of the Process are very complex and difficult. Unfortunately, this is not merely because the editorial style is complex. The underlying thing it is trying to handle is itself complex, and there are deliberate goals we're trying to uphold that result in this complexity.

I think it is absolutely worth out time to spend effort on trying to find ways to both simplify the underlying notions and clarify the text that describes it, but doing so without regressing on what this Process was trying to ensure is probably not going to be easy.

Even then, I think this is likely one of the top priorities for the next cycle of the Process.

[frivoal]

As for using tools to help, any inspiration we can get is great. I am a little skeptical that https://hemingwayapp.com/ will be of much help in this context. It seems more targeted at writing vivid prose than precise rules. I am also unsure of its advice when it comes to non-native speakers. For example, it says to avoid adverbs, and gives the following advice:

For instance, instead of saying that someone is “walking slowly” you can say they “tip-toed” or they “crept.” That way, your writing is more vivid.

This may be a good tip for writing an engaging novel, but I am quite certain that many more people are capable of understanding "walked slowly” than “tip-toed” or “crept" .

[marcoscaceres]

don't know about Hemingwayapp.com, but I'm sure it will find some things.

At the same time, with ChatGTP 4, remember you need to put it into "the right frame of mind" with the prompts. Like,

"Hey Chatty, set yourself to be an expert in international standards, and with the precision of a world class lawyer, and a PhD in Computer Science. I need you to analyze the following text from the W3C's Process document for clarity and precision. I'm a member of the W3C's Advisory Board, and we will be updating the W3C Process document together. As I copy and paste text for you, can you first identify ambiguities in the text and explain why. Then suggest a number of possible corrections. Where you need more context or you are missing definitions, please ask and I can provide them for you. Here is the text full text for the section we are updating:

[TEXT HERE]. 

I want you to analyze paragraph 3 and tell me what you think."

And then, you can ask it logical questions.

Hey Chatty, if X was to happen with Y, what would the outcome be based on the change we have agreed to?

And so on... hope that helps!

Oh, and you can also ask it to keep matching the writing style of the W3C Process document by providing it with sections that you find well written.

[marcoscaceres]

You will still need to edit and carefully review whatever it produces... but it should do a reasonable job at least identifying issues.

And I do encourage you to run simulations on various scenarios. Just to check that the logic is correct. If the prose is algorithmic in nature (if... then), you can even ask it to write the thing out in some formal language (even just JavaScript!) to check the logic with proof cases.

[TallTed]

It's also important to use the latest version of ChatGPT you can. Paid accounts currently have access to 3.5 and 4.0. There's less difference in the output between these than there was between 3.0 and 4.0, but it's still substantial.

[wareid]

I should have followed up earlier with the results of my little experiment on this but sadly, LLMs cannot handle the Process.

I attempted to get it to summarize several sections and it quickly lost context, often mangled the meaning of statements, and basically produced an unusable set of guidelines. It was an interesting exercise though!