From aef41ecd1a0874bdd4eb1a2d6b337c1c672eb27a Mon Sep 17 00:00:00 2001 From: plehegar Date: Wed, 13 Aug 2025 13:19:53 -0400 Subject: [PATCH 1/3] Use ED.css for editor's draft --- editor/editors-draft.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/editor/editors-draft.md b/editor/editors-draft.md index a5c1b1271..dd56114c7 100644 --- a/editor/editors-draft.md +++ b/editor/editors-draft.md @@ -10,17 +10,17 @@ This document, for W3C groups, reflects some discussion within the Team about ho ## Introduction {#intro} -Many Working Groups publish drafts for internal group review between publications on the TR page. In the interest of clarity of the W3C process, we request that Working Groups take care that documents are labeled with their true status. Sometimes labels like "W3C Working Draft" are copied from documents that are truly a product of the W3C Working Draft process to documents that are not, or at least not yet. +Many Working Groups publish drafts for internal group review between publications on the TR page and may expose those to the public as well. In the interest of clarity of the W3C process, we request that Working Groups take care that documents are labeled with their true status. Sometimes labels like "W3C Working Draft" are copied from documents that are truly a product of the W3C Working Draft process to documents that are not, or at least not yet. The guidelines below are intended to reduce confusion between group-internal drafts (some of which are Member-only, while others are public) and published documents that have been through additional W3C processes. Documents that follow these guidelines have no formal standing within W3C. -## Requirements for Group-Internal Drafts {#reqs} +## Requirements for Group-internal Drafts {#reqs} -- In a Working Group, group-internal drafts MUST follow the licensing as defined in its charter. +The Group-internal Drafts must follow the licensing as defined in its charter. Editor's draft must use the style sheet: ***`https://www.w3.org/StyleSheets/TR/2021/W3C-ED.css`*** and must not create confusion with [W3C standards and drafts](https://www.w3.org/TR/). ## Guidelines for Group-Internal Drafts {#guidelines} -1. Use this style sheet: ***`https://www.w3.org/StyleSheets/TR/2021/W3C-ED.css`*** +1. Use 1. Use an appropriate label for the document, as in: ```html

Architecture of the World Wide Web, Volume One

@@ -37,3 +37,4 @@ The guidelines below are intended to reduce confusion between group-internal dra In general, no (but see [Issue #110](https://github.com/w3c/modern-tooling/issues/110)). Please avoid giving the impression that these drafts have formal status within W3C or another body. Please do not label them "W3C Working Draft" in these documents. If you are just attaching a copy of an in-progress draft in email in preparation for a group teleconference, keep in mind that the attachment is archived and may be found by readers who don't have that context. Please erase any indication that this is a W3C Working Draft. + From 620d43f806a070af593eec6c7593707a5599fb1a Mon Sep 17 00:00:00 2001 From: plehegar Date: Wed, 13 Aug 2025 13:44:26 -0400 Subject: [PATCH 2/3] Mention the policy from github documentation --- editor/index.md | 6 +++--- github/specs.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/editor/index.md b/editor/index.md index efed34bb4..82ea3b390 100644 --- a/editor/index.md +++ b/editor/index.md @@ -15,10 +15,10 @@ If you are a newly appointed editor in your Working Group, here is some advice t - Get an [idea of the role of an editor](role.md) at W3C - Check the most popular editing tools: [Bikeshed](https://speced.github.io/bikeshed/), [respec](https://github.com/speced/respec/wiki) +- When using Github, check [Using GitHub for Spec Work](../github/specs.md) and [Workflow for editors and other contributors](./github/workflow.md) +- [How to Organize a Recommendation Track Transition](../transitions/) explains the process to get a document published as a technical report. The [step finder](./transitions/nextstep.md) will help you finding which transition to do next and what the requirements are. - Read the [W3C Publication Rules](https://www.w3.org/pubrules/doc/) (often referred as pubrules) and ask advice on the points that are unclear; if your document doesn't comply with these rules, it cannot be published as a W3C technical report. -- [How to Organize a Recommendation Track Transition](../transitions/) explains the process to get a document published as a technical report. -- The [Pubrules Checker](https://www.w3.org/pubrules/) is a tool that can help you assess whether or not your document complies with pubrules. -- Review [WCAG](https://www.w3.org/TR/WCAG/) +- The [Pubrules Checker](https://www.w3.org/pubrules/) is a tool that can help you assess whether or not your document complies with pubrules. You will still need to keep [WCAG 2.2](https://www.w3.org/TR/WCAG22/) in mind. - All W3C editors are invited to join the [publicly archived mailing list <spec-prod@w3.org>](https://lists.w3.org/Archives/Public/spec-prod/) to share and discuss the techniques and tools used to produce W3C specifications. ## Guidelines on W3C specifications editing {#quality} diff --git a/github/specs.md b/github/specs.md index 9d8a78240..29bfa3678 100644 --- a/github/specs.md +++ b/github/specs.md @@ -22,7 +22,7 @@ toc: false cd reponame ``` 1. **Note: this step and the following are not needed if you set up your repository using the W3C Repository Manager as it can create a basic ReSpec document for you**. -Now we want to create the spec document itself. I use [ReSpec](https://respec.org/docs/), so I simply copy the content of the [default template](https://respec.org/docs/#getting-started) into an `index.html` page at the root of my repository. And then add it to the repository. +Now we want to create the spec document itself. I use [ReSpec](https://respec.org/docs/), so I simply copy the content of the [default template](https://respec.org/docs/#getting-started) into an `index.html` page at the root of my repository. And then add it to the repository. See also the requirements for [Group-internal Drafts](../editor/editors-draft.md#reqs). ```shell git add index.html From c6880b48a7f0513e19437615c4cca2efb4254bab Mon Sep 17 00:00:00 2001 From: plehegar Date: Wed, 13 Aug 2025 13:44:58 -0400 Subject: [PATCH 3/3] P2025: hearbeat requirements are gone --- editor/index.md | 2 +- github/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/editor/index.md b/editor/index.md index 82ea3b390..18ee5fd58 100644 --- a/editor/index.md +++ b/editor/index.md @@ -28,7 +28,7 @@ W3C has developed a set of resources giving advices and guidelines on editing W3 - The [W3C Manual of Style](../manual-of-style/) is a collection of rules you're invited to follow to make your document clearer and adapted to the common style at W3C. - Begun in 1992 and only a little out of date, the [Style Guide for online hypertext](https://www.w3.org/Provider/Style/) by Tim Berners-Lee is a good start on writing for the Web; see also Jakob Nielsen's [How Users Read on the Web](https://www.nngroup.com/articles/how-users-read-on-the-web/) - The [QA Framework: Specification Guidelines](https://www.w3.org/TR/qaframe-spec/) from the W3C Quality Assurance Activity are a work in progress that became a Candidate Recommendation in November 2003. -- The Team has guidelines for a [style for group-internal drafts](editors-draft.md) to avoid confusion with documents published on the [TR page](https://www.w3.org/TR/). Please also review the related [Working Group Heartbeat Requirement](https://www.w3.org/policies/process/#revising-wd) of the W3C Process. +- The Team has guidelines for a [style for group-internal drafts](editors-draft.md) to avoid confusion with documents published on the [TR page](https://www.w3.org/TR/). [Bert Bos's essay on W3C's design principles](https://www.w3.org/People/Bos/DesignGuide/introduction) and [Tim Berners-Lee's essentials of a specification](https://www.w3.org/1999/09/specification) may also be a useful reading. diff --git a/github/index.md b/github/index.md index db6402059..8e87064e0 100644 --- a/github/index.md +++ b/github/index.md @@ -35,7 +35,7 @@ Repositories under the W3C organization may represent the work of Working Groups : If your group accepts contributions from a broad set of people through pull requests, this tool can help you make sure that the contributors have signed the requisite IPR agreements. [Automatic Publication from GitHub](https://github.com/w3c/echidna/wiki/Setting-up-Echidna-as-a-GitHub-hook) -: In general, it is strongly recommended to use [Echidna](https://github.com/w3c/echidna/wiki) to publish TR documents rather than the manual path that goes through the Webmaster (assuming of course that your document is of a supported type). This document explains how to set up your repository using Travis CI in order to automatically publish on every commit (to a given branch) and never again have to worry about what people used to call “heartbeat” publications. With this, you can even get rid of the notion of Editor's Draft altogether. +: In general, it is strongly recommended to use [Echidna](https://github.com/w3c/echidna/wiki) to publish TR documents rather than the manual path that goes through the Webmaster (assuming of course that your document is of a supported type). This document explains how to set up your repository using Github actions in order to automatically publish on every commit (to a given branch). With this, you can even get rid of the notion of Editor's Draft altogether. [Keeping Track with Midgard](https://labs.w3.org/midgard/) : Because work that happens on GitHub is spread out across many repositories, it can be challenging to remain informed about what's going on. Midgard helps there by filtering the data into mailboxes so that you can for instance get all the events for WebRTC repositories. Log in there with your W3C credentials, and just start using it. Note: it does not at this time have many filters and it is likely that your area of interest may not yet have one. If you wish to add one (which is easy) you should read [the documentation on Pheme filters](https://github.com/w3c/midgard/blob/master/DEVELOPMENT.md#libfilterseventsjs).