New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

W3C Process Document for Busy People should start with how to make specs #56

Open
tantek opened this Issue Apr 19, 2018 · 8 comments

Comments

Projects
None yet
3 participants
@tantek
Contributor

tantek commented Apr 19, 2018

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:

  • Making specs to improve the web is why we are here (how are they made? and updated? flow charts)
  • WGs are in service of making specs within a particular area (Charter scope) that are ready (incubation - link Rec Track Readiness)
  • The TAG is in service of making sure specs make sense across WGs.
  • IGs/CGs are in service of incubating proposals towards specs, either to hand-off when ready to an existing WG, or to motivate a new WG. Members can also submit things in service of incubating proposals.
  • Anyone can help start a CG, the W3C Team drives creating IGs, WGs
  • The AC is in service of prioritizing (voting) which WGs and IGs should be created or continue to exist and worth spending W3C resources on. Also voting for the TAG.
  • The AB is in service of the making/updating the process of all the above as efficient and consensus based as possible. The AB is also elected by the AC.
  • Appendix: Other random FYI W3C stuff that doesn't directly impact how specs are made, or the groups that support that: e.g. Communications, Workshops, Liasons.

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.

Label(s): Process

(Originally published at: http://tantek.com/2018/109/b1/start-with-how-make-specs)

@nrooney

This comment has been minimized.

Collaborator

nrooney commented May 3, 2018

Feel free to raise a PR with reordering as you suggest

@nrooney

This comment has been minimized.

Collaborator

nrooney commented May 3, 2018

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!

https://github.com/w3c/Guide

@tantek

This comment has been minimized.

Contributor

tantek commented May 4, 2018

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/)

@vfournier17

This comment has been minimized.

vfournier17 commented Jun 4, 2018

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.

@nrooney

This comment has been minimized.

Collaborator

nrooney commented Aug 24, 2018

Happy to take a PR for this - will close in a month if no comments are left on this issue or no PR arises.

@vfournier17

This comment has been minimized.

vfournier17 commented Aug 28, 2018

What do you mean by a PR? The above isn't sufficient? I don't have time to rewrite the document...

@nrooney

This comment has been minimized.

Collaborator

nrooney commented Sep 13, 2018

Pull Request for changes

@vfournier17

This comment has been minimized.

vfournier17 commented Sep 13, 2018

Please implement the comments I provided and circulate a new draft.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment