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
(update this page as the rationale document now exists)
m (Fix [GitHub repositories] link (thanks xfq))
 
(13 intermediate revisions by 6 users not shown)
Line 1: Line 1:
So you want to take part? You can!
So you want to take part? You can!
* 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 about HTML5 on the [http://blog.whatwg.org/ blog].
* Write articles for our [http://blog.whatwg.org/ blog].
* Write [[HTML5 tutorial|tutorials]] for new authors and for authors moving to HTML5.
* 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 [[demos]] (ideally in a Google Code project).
* Write cool demos.
* [[Implementations|Implement HTML5]]!
* [[: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 from an authoring standpoint would be going through the spec and finding bits that don't make sense. Start with the authoring  view:
The most useful thing would be going through the spec and finding bits that don't make sense.  


http://whatwg.org/html?style=author
https://html.spec.whatwg.org/multipage/
    
    
Then 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 HTML5]].'''
'''See also [[Reviewing]].'''


== 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, IRC, and chatting with Hixie, 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.


It could be as little work or as much work as you would want it to be. One
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.
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

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