[w3c/webpayments] How should the group update documents in 'TR' space? (#167)

TL;DR: There is a way to automatically update documents in the W3C formal publication space and I am curious if the group is open to doing that with our documents once they are formally published.

----

The W3C publication process is somewhat complex.  At the end of the day, formal publications are put up on the W3C site under the /TR/ tree using a "short name" that is approved by the domain lead.  (For the HTTP API it might be something like https://w3.org/TR/payment-http-api).  Initial publication has a lot of [process ](http://www.w3.org/Consortium/Process/) around it (as does any document 'transition').  After that, up until it reaches the status of "Candidate Recommendation", a working group can update the draft as often as they like. If a document is a "Note" it can also be updated at any time.

There are two schools of thought on how often to update:

1) Update periodically (e.g., every 2 months) or when there are significant changes (e.g., all issues are resolved, a new section is added).
2) Update every time the editor(s) merge a change into the main branch.

As with most things in life, there are trade-offs:

With option 1, there is usually a 'call for consensus' in the group to update the publication.  When there are many documents being managed (as in our case) this can be a little burdensome.  However, it means that there are obvious milestones where the group can direct the public to review and comment on things.  Publication in this sort of model is more of an 'event' and often engenders blog posts, tweets, etc.

With option 2, there can be a lot churn in the document that is in TR space.  Also, if there is not a good 'diff-marked' version or a good change log, it can be difficult for reviewers who are not active in the group to evaluate changes.  If it happens often, it is less of an 'event' and people in the wild seem to take less notice of the publication.

To date we have been using option 1 (or a variant of it).  I feel like we have been doing this by default, rather than taking an active decision on which option to use.

So I have opened this issue to ask for a decision of the working group: Should we be publishing every time an editor merges changes, or should we be publishing only when we want there to be an 'event'?

---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/webpayments/issues/167