A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on Chat (such as one of these permanent autoconfirmed members).

What you can do: Difference between revisions

From WHATWG Wiki
Jump to navigation Jump to search
m (Fix [GitHub repositories] link (thanks xfq))
 
(5 intermediate revisions by 4 users not shown)
Line 2: Line 2:
* Review [http://whatwg.org/specs/ the specifications] and [http://whatwg.org/mailing-list#specs send comments]! (See below for details.)
* Review [http://whatwg.org/specs/ the specifications] and [http://whatwg.org/mailing-list#specs send comments]! (See below for details.)
* Write articles for our [http://blog.whatwg.org/ blog].
* Write articles for our [http://blog.whatwg.org/ blog].
* Write [[Authoring|tutorials]] for new authors.
* Write [[Authoring|tutorials]] for new web developers.
* Monitor and respond to questions on [http://www.whatwg.org/mailing-list#help the help list] and [http://forums.whatwg.org/ the forums].
* Maintain the document explaining the [[rationale]] of the decisions behind the spec. (See below for details.)
* Maintain the document explaining the [[rationale]] of the decisions behind the spec. (See below for details.)
* Help to edit the [[FAQ]].
* Write [[test cases]].
* Write [[test cases]].
* Write cool demos.
* Write cool demos.
* [[:Category:Implementations|Implement HTML]]!
* [[:Category:Implementations|Implement HTML]]!
* Edit one of the many [[companion specifications]] that are lacking editors.
* Edit one of the many [[Specs todo|companion specifications]] that are lacking editors.


== Sending feedback ==
== Sending feedback ==
The most useful thing would be going through the spec and finding bits that don't make sense.  
The most useful thing would be going through the spec and finding bits that don't make sense.  


http://whatwg.org/html
https://html.spec.whatwg.org/multipage/
    
    
You can use the widget at the bottom right (it says "Click the location of the error to select it, then type your message here:") to submit review comments on the spec. The best review comments are those along the lines  of questions you couldn't find the answer to. For example, say you wanted to find out what elements you could put in a <p> element, and you couldn't work it out. Then you would file a bug "I couldn't find the answer to the question 'What elements are allowed inside <p> elements'.".
You can use the link at the bottom (it says "File an issue about the selected text") to submit review comments on the spec. The best review comments are those along the lines  of questions you couldn't find the answer to. For example, say you wanted to find out what elements you could put in a <p> element, and you couldn't work it out. Then you would file a bug "I couldn't find the answer to the question 'What elements are allowed inside <p> elements'.".


'''See also [[Reviewing]].'''
'''See also [[Reviewing]].'''
Line 22: Line 20:
== A rationale document ==
== A rationale document ==


It basically would consist of watching the e-mail lists, the Bugzilla
It basically would consist of watching the [https://github.com/whatwg GitHub repositories] that are of interest,
bugs, asking questions on [[IRC]], and then writing documentation to
asking questions on [[IRC]], and then writing documentation to
explain the thinking behind different parts of the spec on the [[rationale]] page.
explain the thinking behind different parts of the spec on the [[rationale]] page.


Line 31: Line 29:
= How you can improve HTML =
= How you can improve HTML =


''This is the text of an article Hixie wrote.''
''This text originated from an article Hixie wrote.''


Are you trying to do something on the Web that you find you can't do because HTML simply doesn't have a way to do it?
Are you trying to do something on the Web that you find you can't do because HTML simply doesn't have a way to do it?


With your help, we can improve HTML, add a feature to address your problem, and in five to ten years you'll finally be able to do it!
With your help, we can improve HTML, add a feature to address your problem, and in a few years you'll finally be able to do it!


Here's how:
Here's how:


First, write a description of the problem. What are you trying to do? This should be a high-level description. One way to see if you're describing it at a high
First, write a brief user-centric description of the problem. What are you trying to do? This should be a high-level description. One way to see if you're describing it at a high
enough level is to consider whether your description makes as much sense for a Web developer as it does for, say, a mobile phone native app developer. So if your
enough level is to consider whether your description makes as much sense for a Web developer as it does for, say, a mobile phone native app developer. So if your
description talks about HTML elements or JavaScript or HTTP headers, then it's probably too low level. If it talks about what a user sees, how a user interacts
description talks about HTML elements or JavaScript or HTTP headers, then it's probably too low level. If it talks about what a user sees, how a user interacts
with a computer or device, or how a user uses a computer or device to create some sort of content or effect some sort of change, then you're on the right path.
with a computer or device, or how a user uses a computer or device to create some sort of content or effect some sort of change, then you're on the right path.
If you hear people referring to "use cases", it is to this problem description that they refer.
If you hear people referring to "use cases", it is to this problem description that they refer. Some of the most useful information you can give is examples of what
people are currently doing to work around the problem (e.g. they're writing native apps instead of Web pages, or they're using Flash or other extensions, etc).


In particular, your description should not be a solution. Don't propose new elements or attributes, new APIs, new semantics, new features. The time for
In particular, your description should not be a solution. Don't propose new elements or attributes, new APIs, new semantics, new features. The time for
Line 50: Line 49:
Next, do one or more of the following with this description:
Next, do one or more of the following with this description:


0. Discuss the topic on our [[IRC]] channel (#whatwg on Freenode) to see if you've missed anything obvious
* Discuss the topic on our [[IRC]] channel (#whatwg on Freenode) to see if you've missed anything obvious
* Post it as an issue at http://whatwg.org/newbug


1. Post it to [email protected]
Participate in any resulting discussions. Post a link to your issue to your own blog or to other social media sites to
 
2. Post it on http://forums.whatwg.org/
 
3. Visit our IRC channel (#whatwg on Freenode) and ask for help posting it on our blog at http://blog.whatwg.org/
 
4. Post it as a bug report at http://whatwg.org/newbug (you'll need to create an account)
 
Participate in any resulting discussions. Post a link to your e-mail, forum post, blog post, or bug report to your own blog or to other social media sites to
encourage others to participate. For best results, I recommend that you avoid creating new places for the discussion to occur (e.g. new mailing lists, wiki
encourage others to participate. For best results, I recommend that you avoid creating new places for the discussion to occur (e.g. new mailing lists, wiki
pages, or working groups). Keeping the discussions in existing places ensures that experience participants will see your discussions and will be able to
pages, or working groups). Keeping the discussions in existing places ensures that experience participants will see your discussions and will be able to
Line 71: Line 63:
(You don't have to, though, and there's no guarantee that the solutions you propose will be adopted rather than some other ones.)
(You don't have to, though, and there's no guarantee that the solutions you propose will be adopted rather than some other ones.)


If you posted on the forums or on the blog, then once the discussion has settled down, ask for someone (e.g. zcorpan, for the forums, or whoever you spoke to on
When it comes to updating the standard, see https://whatwg.org/working-mode for what the process is. It boils down to writing a pull request for the standard and
IRC, for the blog) to forward your proposal to the main whatwg@whatwg.org mailing list. This will get the topic onto my (Hixie's) radar. (Bugs are all already
writing test cases, and getting support from implementers.
also on the radar, so you don't have to worry about those.)
 
Eventually, I will see the e-mail(s) or bug. This can take a few months, because there's a lot of feedback to go through. I then take all the information in the
thread, related forum posts and blog posts, and anything else I can find; I sometimes talk to browser vendors, bring the topic up on IRC for some sanity checking
with whoever is online, etc. And then I write a reply to all the e-mails, and possibly update the spec accordingly. Lather, rinse, repeat.                            


You may ask why browser vendors have a prominent role in this process. The answer is simple. The specification is not magical; it cannot force browser vendors to
You may ask why browser vendors have a prominent role in this process. The answer is simple. The specification is not magical; it cannot force browser vendors to
Line 86: Line 73:


If you want to participate in the process in ways other than reporting problems you find with the Web, there are various things you can do: participate in
If you want to participate in the process in ways other than reporting problems you find with the Web, there are various things you can do: participate in
discussions on the mailing list, forums, blog, or bug system; chat with us on IRC (#whatwg on Freenode); write test cases; write tutorials; review the spec...
discussions on GitHub; chat with us on IRC (#whatwg on Freenode); write test cases; write tutorials; review the spec...
The best place to start is to join us on IRC and ask what you can do.
The best place to start is to join us on IRC and ask what you can do.


We also have a FAQ: http://wiki.whatwg.org/wiki/FAQ
We also have a FAQ: https://whatwg.org/faq

Latest revision as of 12:12, 24 August 2017

So you want to take part? You can!

Sending feedback

The most useful thing would be going through the spec and finding bits that don't make sense.

https://html.spec.whatwg.org/multipage/

You can use the link at the bottom (it says "File an issue about the selected text") to submit review comments on the spec. The best review comments are those along the lines of questions you couldn't find the answer to. For example, say you wanted to find out what elements you could put in a <p> element, and you couldn't work it out. Then you would file a bug "I couldn't find the answer to the question 'What elements are allowed inside <p> elements'.".

See also Reviewing.

A rationale document

It basically would consist of watching the GitHub repositories that are of interest, asking questions on IRC, and then writing documentation to explain the thinking behind different parts of the spec on the rationale page.

It could be as little work or as much work as you would want it to be. One could easily imagine this becoming a group effort.

How you can improve HTML

This text originated from an article Hixie wrote.

Are you trying to do something on the Web that you find you can't do because HTML simply doesn't have a way to do it?

With your help, we can improve HTML, add a feature to address your problem, and in a few years you'll finally be able to do it!

Here's how:

First, write a brief user-centric description of the problem. What are you trying to do? This should be a high-level description. One way to see if you're describing it at a high enough level is to consider whether your description makes as much sense for a Web developer as it does for, say, a mobile phone native app developer. So if your description talks about HTML elements or JavaScript or HTTP headers, then it's probably too low level. If it talks about what a user sees, how a user interacts with a computer or device, or how a user uses a computer or device to create some sort of content or effect some sort of change, then you're on the right path. If you hear people referring to "use cases", it is to this problem description that they refer. Some of the most useful information you can give is examples of what people are currently doing to work around the problem (e.g. they're writing native apps instead of Web pages, or they're using Flash or other extensions, etc).

In particular, your description should not be a solution. Don't propose new elements or attributes, new APIs, new semantics, new features. The time for discussions of solutions is later.

Next, do one or more of the following with this description:

  • Discuss the topic on our IRC channel (#whatwg on Freenode) to see if you've missed anything obvious
  • Post it as an issue at http://whatwg.org/newbug

Participate in any resulting discussions. Post a link to your issue to your own blog or to other social media sites to encourage others to participate. For best results, I recommend that you avoid creating new places for the discussion to occur (e.g. new mailing lists, wiki pages, or working groups). Keeping the discussions in existing places ensures that experience participants will see your discussions and will be able to lend you their experience. The most important part of these discussions is clarifying how common the problem is, what related problems other people have that could maybe be addressed at the same time, and what work-arounds exist to avoid the problem.

Ideally, some browser vendors will at this point start commenting on the problem, hopefully saying that they agree that it's a problem. Getting browser vendors to believe there's a problem is the second best thing that you can do to ensure your problems gets solved. (The best thing that can happen is for browser vendors to implement a solution. See notes below.) Once you have browser vendors buying-in to the problem's importance, you can start talking about possible solutions. (You don't have to, though, and there's no guarantee that the solutions you propose will be adopted rather than some other ones.)

When it comes to updating the standard, see https://whatwg.org/working-mode for what the process is. It boils down to writing a pull request for the standard and writing test cases, and getting support from implementers.

You may ask why browser vendors have a prominent role in this process. The answer is simple. The specification is not magical; it cannot force browser vendors to do anything they don't want to do. If I write something in the spec and they don't implement it, there's nothing we can do: the feature doesn't really exist, it's just fiction, and we've all wasted our time. To avoid wasting my time, I try to work with the browser vendors to make sure that what I specify is something they're willing to implement. (It doesn't always work out that way, but then after a while I update the spec to match what they did do, or didn't do, e.g. removing things that nobody has implemented.)

If you want to participate in the process in ways other than reporting problems you find with the Web, there are various things you can do: participate in discussions on GitHub; chat with us on IRC (#whatwg on Freenode); write test cases; write tutorials; review the spec... The best place to start is to join us on IRC and ask what you can do.

We also have a FAQ: https://whatwg.org/faq