Skip to content

Use ED.css for editor's draft #350

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions editor/editors-draft.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm guessing you meant to remove the whole line

1. Use an appropriate label for the document, as in:
```html
<h1>Architecture of the World Wide Web, Volume One</h1>
Expand All @@ -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.

8 changes: 4 additions & 4 deletions editor/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Check the most popular editing tools: [Bikeshed](https://speced.github.io/bikeshed/), [respec](https://github.com/speced/respec/wiki)
- Check the most popular editing tools: [Bikeshed](https://speced.github.io/bikeshed/), [respec](https://respec.org/docs/)

- When using Github, check [Using GitHub for Spec Work](../github/specs.md) and [Workflow for editors and other contributors](./github/workflow.md)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- When using Github, check [Using GitHub for Spec Work](../github/specs.md) and [Workflow for editors and other contributors](./github/workflow.md)
- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [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.
- [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 &lt;spec-prod@w3.org&gt;](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}
Expand All @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion github/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion github/specs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down