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

Review on utilization of `w-nodev` annotation #1488

Closed
momdo opened this Issue Jul 2, 2016 · 9 comments

Comments

4 participants
@momdo
Contributor

momdo commented Jul 2, 2016

Currently, we have the w-nodev annotation to mark-up information mainly for implementers. As mentioned in #626 (comment) by Anne, however, the tag is not maintained perfectly.

For example, algorithm parts in the description of the ruby element lack w-nodev. (Particularly, "At any particular time, the segmentation and categorisation of content of a ruby element is the result that would be obtained from running the following algorithm:" in https://html.spec.whatwg.org/multipage/semantics.html#the-ruby-element ) Since the portion is very large, it is somewhat hard to read through the section in order to get the idea about how the ruby element should be used and how the element works.

In any case, the proposal here is to review the usage of w-nodev and update the existing documents by adding/removing w-nodev tags accordingly.

This attempt should enable Web developers all over the world to concentrate on developer-oriented information. Moreover, it also accelerates translation projects to publish the most-demanded translations for developers quickly.

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Jul 2, 2016

Member

We would definitely welcome help in adding w-nodev more appropriately. I think it's something we should all be more aware of when doing pull requests, but specific targeted fixes would also be a good idea. We can try to fix the ruby algorithms, although a pull request would also be great.

Member

domenic commented Jul 2, 2016

We would definitely welcome help in adding w-nodev more appropriately. I think it's something we should all be more aware of when doing pull requests, but specific targeted fixes would also be a good idea. We can try to fix the ruby algorithms, although a pull request would also be great.

@domenic domenic added the spec tooling label Jul 2, 2016

@annevk

This comment has been minimized.

Show comment
Hide comment
@annevk

annevk Jul 4, 2016

Member

I think another problem is that https://developers.whatwg.org/ is increasingly outdated and therefore we don't really have a good output view of these annotations. @benschwarz, any updates on that or anything we can do to help?

Member

annevk commented Jul 4, 2016

I think another problem is that https://developers.whatwg.org/ is increasingly outdated and therefore we don't really have a good output view of these annotations. @benschwarz, any updates on that or anything we can do to help?

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Jul 6, 2016

Member

@annevk I have a local version of dev edition, updated, created using the new pipeline. It is missing a number of things compared to the current dev edition though, which I listed in whatwg/wattsi#27. If someone had time to work on those we'd be in much better shape.

Member

domenic commented Jul 6, 2016

@annevk I have a local version of dev edition, updated, created using the new pipeline. It is missing a number of things compared to the current dev edition though, which I listed in whatwg/wattsi#27. If someone had time to work on those we'd be in much better shape.

@benschwarz

This comment has been minimized.

Show comment
Hide comment
@benschwarz

benschwarz Jul 6, 2016

@domenic Is the idea that you'll replace developers.whatwg.org with your implementation? Or do you want to merge it?

benschwarz commented Jul 6, 2016

@domenic Is the idea that you'll replace developers.whatwg.org with your implementation? Or do you want to merge it?

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Jul 6, 2016

Member

@benschwarz I was thinking merge? Maybe move into the whatwg/ GitHub org and add all the current collaborators? What do you think?

It's still a ways out though as the Wattsi splitting issue seems non-trivial... unless we're OK with having large sections, I guess.

Member

domenic commented Jul 6, 2016

@benschwarz I was thinking merge? Maybe move into the whatwg/ GitHub org and add all the current collaborators? What do you think?

It's still a ways out though as the Wattsi splitting issue seems non-trivial... unless we're OK with having large sections, I guess.

@benschwarz

This comment has been minimized.

Show comment
Hide comment
@benschwarz

benschwarz commented Jul 7, 2016

@domenic Perfect 👍

domenic added a commit that referenced this issue Jun 22, 2017

Meta: changes to support a revamped developer's edition
This new dev edition is meant to supercede
https://developers.whatwg.org/. It is located at
https://html.spec.whatwg.org/dev/. Closes
benschwarz/developers.whatwg.org#104.

This introduces a developers stylesheet derived from
https://github.com/benschwarz/developers.whatwg.org/tree/97ff943a8f5b8fe38f78e224b4b44b472ccefb57/sass,
including the web fonts. We host the web fonts in this repository,
instead of using Google Fonts, as Google Fonts is blocked in China.
Further help on improving the design of the dev edition going forward is
appreciated; for now we have done a straight port.

It also updates the source document significantly to make the generated
output work better for the dev edition. Special care was given to the
web workers section, and to ensuring that every element definition
references which interface it corresponds to. Further work on properly
marking up the source document is tracked in #1488.

This new version is missing several features from the old one. In rough
order of importance:

* Search
* Working offline
* "About this specification" introduction on the index page
* Nice footer and header navigation UI on each non-index page
* A distinct favicon

We plan to add most of these back over time.

@domenic domenic added dev edition and removed spec tooling labels Jun 22, 2017

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Jun 22, 2017

Member

The new dev edition is live!! https://html.spec.whatwg.org/dev/

It definitely needs help adding w-nodev as appropriate. We did some of that in 28b739e, but we really need to go through section-by-section. @momdo or anyone else, any help would be appreciated. Let us know if there are specific sections you are working on so we can avoid duplicating work.

I will work on a document with guidelines as to what to be included or not.

Member

domenic commented Jun 22, 2017

The new dev edition is live!! https://html.spec.whatwg.org/dev/

It definitely needs help adding w-nodev as appropriate. We did some of that in 28b739e, but we really need to go through section-by-section. @momdo or anyone else, any help would be appreciated. Let us know if there are specific sections you are working on so we can avoid duplicating work.

I will work on a document with guidelines as to what to be included or not.

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Jun 28, 2017

Member

The guidelines are now available at https://github.com/whatwg/html/blob/master/CONTRIBUTING.md#the-developers-edition. We've also published a blog post about the new developer's edition: https://blog.whatwg.org/developers-edition-comeback

If someone wants to help, here is a very simple starter project: exclude the entire "IANA considerations" section from the output, as it is not developer-relevant. This will just consist of finding the appropriate place in the source to add <div w-nodev> and </div> to encompass all of that.

Member

domenic commented Jun 28, 2017

The guidelines are now available at https://github.com/whatwg/html/blob/master/CONTRIBUTING.md#the-developers-edition. We've also published a blog post about the new developer's edition: https://blog.whatwg.org/developers-edition-comeback

If someone wants to help, here is a very simple starter project: exclude the entire "IANA considerations" section from the output, as it is not developer-relevant. This will just consist of finding the appropriate place in the source to add <div w-nodev> and </div> to encompass all of that.

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic
Member

domenic commented Jun 28, 2017

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