Join GitHub today
W3C Process Document for Busy People should start with how to make specs #56
Goal: Process Document for Busy People should be tailored to key busy people: technical editors and contributors. They most often need to know how to make progress on a spec. This doc should start there and describe how everything else is in service of it.
tl;dr start with the actual work product of the W3C, specifications, then go meta one step at a time, section by section. Rough outline:
Modest proposal: start with W3C Recommenation (Technical Report) Flow: The "Recommendation Track" — that diagram is key and perhaps the most referenced thing (second perhaps is the Modifying a W3C Recommendation diagram and section). Include all the material up through just before Communication.
Everything else, e.g. W3C Groups, TAG, AC, AB, Leadership section should all follow from there.
(Originally published at: http://tantek.com/2018/109/b1/start-with-how-make-specs)
Actually looking at this again your scope seems to be looking to create something completely different - something more tailored to /guide than what is done here.
Process Doc for Busy People Goal: make the process doc easier to understand for all W3C stakeholders (as stated on IRC the name is inspired from the Japanese for Busy People textbooks which also try to make something difficult much easier for many people). All stakeholders means (not an exclusive list) the team, chairs, invited experts, participants, editors, AC, TAG, AB, people who like the W3C and want to know more, and peoples from all around the world with different levels of language proficiency.
You're describing something which would be amazing for /guide - maybe suggest it there? We're doing work to improve this too!
I should have said prioritized for rather than tailored to.
I agree with your stated goal and scope of "make the process doc easier to understand for all W3C stakeholders". The current content certainly helps with that goal, and I am hoping that re-ordering the content as I am suggesting would help even more.
I stand by the title suggestion: W3C Process Document for Busy People should start with how to make specs
I believe this will serve all W3C stakeholders as you described, and here is why (additional thinking compared to initial issue description).
(I wrote a version of this shortly after this morning’s meeting in IRC, and will repeat here to help move this forward.)
The very name of "Process Doc for Busy People" implies that time (or lack of it - being busy) is the prime priority (saving time in particular) and design center of the document.
Thus beyond who it is for, if we recognize that some things in the process happen far more often (and thus require referring to the process more frequently) than others, we can take that prime priority of saving time, and implement it by ordering process section by frequency of use, thus saving more people more time more often, since they will take less time to find their more frequent uses.
E.g. iterating on specs happens more often than AC votes on transitioning specs happens more often than AC votes on WG (re)charters happens more often than votes on TAG/AB elections, happens more often than host agreement(s) being iterated, happens more often than change of Director. (illustrative, not exhaustive list)
This is roughly similar to (though not the same as) the order I initially listed, yet this updated thinking is based on more objective criteria.
Thank you for the invitation to raise a PR.
If this line of thinking (ordering sections by frequency of use, most to least) sounds appealing, I can work on a new explicit section list order accordingly, and presuming that has consensus, can work on a pull request for it, all while maintaining the narrative style so the whole document still flows well.
(Originally published at: http://tantek.com/2018/123/t2/)
I’ve reviewed this document and, while I support the general idea of providing an overview that newcomers can understand, I have some concerns about this summary. Often, when you try to condense a complicated document like the Process Document and convert it to "plain English,” you end up with statements that aren’t quite correct. Although the “disclaimer” notice at the beginning of the document helps, it should also say that in the event of any conflict between the summary and the Process Document, the Process Document will be the controlling document in all cases. The summary should be viewed as “non-normative" and should not be used to interpret the Process Document.
One example of this is the “Charter Extensions” section. This section seems to say that the Director can extend any charter, even if substantively modified, by simply announcing the extension to the AC. We know this is not correct when substantive changes have been made to a charter like adding new deliverables. Someone reading this section who does not also read the Process Document itself could be left with the misimpression that the charter can be completely changed upon a charter extension with just the Director’s approval.
Another example is in the Candidate Recommendation section. This section states that the Candidate Recommendation stage triggers a “Call for Exclusions” detailed in the W3C Patent Policy. As we know, it’s not a “stage” that triggers an exclusion opportunity, it’s the publication of a particular draft, such as a FPWD or CR. I would actually prefer not to include any statements about the PP in the summary. This may be considered one of those areas where one might thing "Why dod we need to be so precise? Everyone knows what we mean." My concern is that we could create ambiguity/inconsistency by having different language in the Patent Policy, Process Document, and this summary, which could cause disputes. We need all of these documents to be as consistent as possible.
The diagram in the “Modifying a W3C Recommendation” section does not make sense to me. Wouldn’t it make more sense to start with the Recommendation and then show the various routes it can go? It doesn’t make sense to me to start with the FPWD when you’re talking about modifying a Recommendation. I understand that this diagram appears in the Process Document as well, and I believe I made similar comments about it when it was added there as well.
In addition, there are a number of typos and misspellings throughout the document.
I think this summary needs more discussion and revision before it's ready for prime time. I'm happy to help however I can - please let me know.