From 9fd8c73c20f81cd5e841a44e195ee1568576e78d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philip=20J=C3=A4genstedt?= Date: Wed, 9 Aug 2017 14:26:10 +0200 Subject: [PATCH] Move the generic WHATWG parts of wiki/FAQ to whatwg.org/faq This was produced starting from the HTML output of https://wiki.whatwg.org/wiki/FAQ and cleaning it up to match the style of /working-mode and /code-of-conduct. New IDs were minted, but no changes to the text content was made, verified using https://github.com/foolip/epubbase/blob/master/worddiff.py. Some minimal amount of style is carried over or invented to make it not much worse than the old FAQ. --- src/.htaccess | 1 - src/code-of-conduct | 1 + src/faq | 315 ++++++++++++++++++++++++++++++++++++++++++++ src/specs/index | 1 + src/working-mode | 1 + 5 files changed, 318 insertions(+), 1 deletion(-) create mode 100644 src/faq diff --git a/src/.htaccess b/src/.htaccess index f39ff99b2..8a1e572bd 100644 --- a/src/.htaccess +++ b/src/.htaccess @@ -84,7 +84,6 @@ redirect permanent /x https://xhr.spec.whatwg.org/ redirect permanent /xhr https://xhr.spec.whatwg.org/ redirect permanent /newbug https://github.com/whatwg/html/issues/new -redirect permanent /faq https://wiki.whatwg.org/wiki/FAQ # redirect permanent /) https://whatwg.org/ redirect permanent /mailing-list) https://whatwg.org/mailing-list diff --git a/src/code-of-conduct b/src/code-of-conduct index 1e7a32e53..ab9416297 100644 --- a/src/code-of-conduct +++ b/src/code-of-conduct @@ -16,6 +16,7 @@
  • Standards
  • Working Mode
  • Code of Conduct
    • +
  • FAQ

    • Code of Conduct

    diff --git a/src/faq b/src/faq new file mode 100644 index 000000000..ee0a5384c --- /dev/null +++ b/src/faq @@ -0,0 +1,315 @@ + + + + Web Hypertext Application Technology Working Group FAQ + + + + + +

    + The + Web Hypertext Application Technology + Working Group +

    + + +

    FAQ

    + +

    The WHATWG

    + +

    What is the WHATWG?

    + +

    The Web Hypertext Application Technology Working Group (WHATWG) is a growing community of + people interested in evolving the Web. It focuses primarily on the development of HTML and APIs + needed for Web applications. + +

    The WHATWG was founded by individuals of Apple, the Mozilla Foundation, and Opera Software in + 2004, after a W3C workshop. Apple, Mozilla and Opera were becoming increasingly concerned about + the W3C’s direction with XHTML, lack of interest in HTML and apparent disregard for the needs of + real-world authors. So, in response, these organisations set out with a mission to address these + concerns and the Web Hypertext Application Technology Working Group was born. + +

    How do you spell and pronounce WHATWG?

    + +

    It is spelled WHATWG, all uppercase, no spaces. It has various pronunciations: what-wee-gee, + what-wig, what-double-you-gee. + +

    What is the WHATWG working on?

    + +

    The WHATWG's main focus is Web standards, specifically: + +

    + +

    ...and a number of other specs. + +

    How can I get involved?

    + +

    There are lots of ways you can get involved, take a look and see + What you can do! + +

    This video from Domenic Denicola is a + good introduction to working with standards bodies. + +

    Is participation free?

    + +

    Yes, everyone can contribute. There are no memberships fees involved, it's an open process. You + may easily participate on GitHub or subscribe to the + WHATWG mailing lists. There are no meetings, since meetings prevent + people with limited time or money from participating. + +

    Is there a Code of Conduct?

    + +

    Yes, see Code of Conduct. Please read it and respect it. + +

    The WHATWG Process

    + +

    How does the WHATWG work?

    + +

    People collaborate on GitHub or send email to + the mailing list. + +

    Each standard has one or more editors, who are responsible for dealing with feedback for that + document. Those editors read all the feedback, and, taking it into account along with research, + studies, and feedback from many other sources (blogs, forums, IRC, etc.) make language design + decisions intended to address everyone's needs as well as possible while keeping the languages and + APIs consistent. + +

    This continues, with people sending more feedback, until nobody is able to convince the + relevant editor to change the spec any more (e.g., because two people want opposite things, and + the editor has considered all the information available and decided that one of the two proposals + is the better one). + +

    For new features, or significant changes to the processing models, the relevant editor will + typically describe the intended changes in the relevant bug or mailing list thread to give people + a chance to point out problems with it before the spec is updated. Implementors, especially, are + urged to indicate on such threads whether they approve of the suggested changes or new feature, so + that we can avoid the spec containing material which implementors are later found to disagree + with. + +

    This is not a consensus-based approach — there's no guarantee that everyone will be happy! + There is also no voting. There is a small oversight committee (known historically as the "WHATWG + members", from the name that the original charter used, though that + terminology is misleading) who have the authority to override or replace editors if they start + making bad decisions, but so far that has never happened in over ten years. This committee has a + private mailing list, but it receives very few messages, usually going years with no emails at + all. Discussions on that list are summarized and described on the public list, to make sure + everyone is kept up to date. + +

    What happens with WHATWG mailing list/GitHub issue discussions?

    + +

    On the WHATWG list and in WHATWG issues on GitHub, the burden is on the spec editors to + evaluate the various positions that have been put forward in a discussion, and figure out which + one is strongest (or find another position that strikes a better balance between all of them). + +

    The purpose of debate at the WHATWG therefore isn't to convince everyone; it is to put forward + the arguments that exist, so that the relevant editor can make a well-informed decision. As a + corollary: If some points are made, rebutted, and not further defended, then maybe the person + making the arguments is hoping that the relevant editor will consider the rebuttals weak, or + thinks that the argument they have presented is strong despite the rebuttals. If you find someone + is not making good arguments, or is ignoring your arguments, your best bet is to stop responding. + Repeating previously-stated arguments doesn't help, since the editors will see all the arguments + when they look at the thread. Similarly, as soon as threads start being meta-threads about + people's argumentation behaviour, we stop making any kind of useful progress, since that isn't + input that can help the decision-making process later. + +

    How should tool developers, screen reader developers, browser vendors, search engine vendors, and other implementors interact with the WHATWG?

    + +

    File an issue on the relevant standard as indicated at + the top of that standard. All feedback is supposed to be addressed in due course. You are also + welcome to take a stab at addressing the problem yourself through a GitHub pull request. + +

    If you want feedback to be dealt with faster than "eventually", e.g., because you are about + to work on that feature and need the spec to be updated to take into account all previous + feedback, let the editors know by either emailing them, or contacting them on + IRC. Requests for priority feedback handling are + handled confidentially if desired so other implementers won't know that you are working on that + feature. + +

    Is there a process for removing bad ideas from a specification?

    + +

    There are several processes by which we trim weeds from the specifications. + +

    + +

    Removing features is a critical part of spec development. + +

    Is there a process for adding new features to a specification?

    + +

    The process is rather informal, but basically boils down to this: + +

      +

    1. Forget about the particular solution you have in mind! Solution time is later! + +

    2. Write down a description of the underlying problem you're trying to solve. What are the + use cases? A use case is an actual user wanting to do something. Then list requirements for each + use case. For a good example of how to do this, see + this email. + +

    3. Get more people involved. Open a new issue in + whatwg/html on GitHub that describes the use + cases and their requirements. Ask fellow Web developers about their opinions (but remind them of + step 1 above). Adjust the list of use cases and requirements as appropriate. Say which use cases + are important and which are just nice to have. + +

    4. Optionally, your work is done at this point. If you have done a good job of the above + steps and convinced other people that your use case is an important one to solve, they can do the + remaining steps. (On the flip side, if nobody else cares about the use case, chances are + solutions for it will not succeed despite being awesome.) + +

    5. Research existing solutions. Come up with new solutions. Try to keep the solutions as + simple as possible, maybe only addressing the important use cases and leaving the nice to have + use cases for later (when there's implementation experience). Send this list of solutions, old + and new, as a comment on the feature's issue. Ask browser vendors for feedback. Maybe some + particular solutions don't fit with the browser's architecture, optimizations, etc., and just are + not going to be implemented no matter how much you like them. Strike those solutions and don't + grieve about the loss! + +

    6. Evaluate how well each of the remaining solutions address each use case and how well they + meet the requirements. This step should show which solution is the technically best fit (might + turn out to be someone else's solution). + +

    7. Ask the spec's editor to put that solution in the spec, or create a pull request on GitHub + yourself. Possibly your text won't be taken verbatim but will be written in a style that is more + suitable for implementors or better hooks in to the rest of the spec, etc. + +

    8. Ask browser vendors to implement the newly specified solution, even if it's just an + experimental implementation. This implementation experience usually means that new problems are + found with the solution that need to be addressed, or that a different solution is actually + better. + +

    9. Write a test suite for the feature to see if the implementations match the spec. This + usually highlights bugs in the implementations and also bugs in the spec. + +

    10. Participate in subsequent design discussions. When there are two or more mature + implementations, it may be time to extend the feature to address the nice to have use cases (but + this whole process should be repeated even for such extensions). +

    + +

    If the idea survives the above design process, the spec will be eventually updated to reflect + the new design. Implementations will then be updated to reflect the new design (if they aren't, + that indicates the new design is not good, and it will be reworked or removed). The spec will be + updated to fix the many problems discovered by authors and implementors, over a period of several + years, as more authors and implementors are exposed to the design. Eventually, a number of + provably interoperable implementations are deployed. At this point development of the feature is + somewhat frozen. + +

    Writing a comprehensive test suite is also an important step, which can even start before + implementations start being written to the spec. Cross-browser tests for HTML are maintained in + w3c/web-platform-tests/html + on GitHub. + +

    Should I send new proposed text when I have a suggestion?

    + +

    Please do not suggest new text, instead, say what is wrong with the current text. Just + proposing new text makes it impossible for the editor to determine if the problem is endemic + (requiring more changes than you realise), or whether what the editor thinks of as mistakes in the + new proposed text are intentional or not (and should be fixed or not), or whether stylistic + differences are intentional or not, etc. + +

    What does "Living Standard" mean?

    + +

    The WHATWG specifications are described as Living Standards. This means that they are standards + that are continuously updated as they receive feedback, either from Web designers, browser + vendors, tool vendors, or indeed any other interested party. It also means that new features get + added to them over time, at a rate intended to keep the specifications a little ahead of the + implementations but not so far ahead that the implementations give up. + +

    Despite the continuous maintenance, or maybe we should say as part of the continuing + maintenance, a significant effort is placed on getting the specifications and the implementations + to converge — the parts of the specification that are mature and stable are not changed willy + nilly. Maintenance means that the days where the specifications are brought down from the mountain + and remain forever locked, even if it turns out that all the browsers do something else, or even + if it turns out that the specification left some detail out and the browsers all disagree on how + to implement it, are gone. Instead, we now make sure to update the specifications to be detailed + enough that all the implementations (not just browsers, of course) can do the same thing. Instead + of ignoring what the browsers do, we fix the spec to match what the browsers do. Instead of + leaving the specification ambiguous, we fix the the specification to define how things work. + +

    Does that mean the specifications can change at any time?

    + +

    The specifications do not change arbitrarily: we are extremely careful! As parts of a + specification mature, and implementations ship, the spec cannot be changed in + backwards-incompatible ways (because the implementors would never agree to break compatibility + unless for security reasons). The specifications are never complete, since the Web is continuously + evolving. The last time HTML was described as "complete" was after HTML4, when development stopped + for several years, leading to stagnation. (If the Web is replaced by something better and dies, + the HTML spec will die with it.) + +

    For references to stable copies of the specifications, some WHATWG specifications follows a + process by which each change to the specification (embodied in a commit) triggers the publication + of a frozen snapshot of the said specification. + +

    These snapshots are published as historical references. The WHATWG intends to keep these frozen + snapshots available at their published URL permanently. + +

    What's the patent story for WHATWG standards?

    + +

    The WHATWG operates as a W3C Community Group and thus uses the W3C Community Group patent + policies. So far we have published one FSA with + patent commitments from + Google, Mozilla, and others covering the URL standard. + You can make patent commitments too! + Some of our specifications have also been forked and republished by the W3C with patent + commitments from certain companies. + +

    What is the process for translating WHATWG standards?

    + +

    Many WHATWG standards have been translated into other languages by the WHATWG community. This + is great, and highly encouraged! + +

    In general, if you translate a WHATWG Standard, please communicate with the maintainers of the + standard (e.g. via a GitHub issue) letting them know about your work. In general this will lead to + adding a link to your translation to the top of the original specification, to allow interested + readers to view it. You can see examples of this in many WHATWG standards, e.g. + https://streams.spec.whatwg.org/. + +

    Such translations are not normative (i.e., implementations should be sure to consult the + original). Due to the nature of living standards, which can change often, it's possible for + translations to become out of date compared to the original standard. If the translation shows + signs of no longer being maintained, or has other quality problems, community members are + encouraged to provide feedback to the maintainers of the standard, so that any links to the + translation can be removed in order to avoid confusing readers. + +

    Note that WHATWG specifications are always licensed under liberal licenses that allow the + creation of derivative works like translations. + + + diff --git a/src/specs/index b/src/specs/index index 0d9ef1946..d5b4c7048 100644 --- a/src/specs/index +++ b/src/specs/index @@ -17,6 +17,7 @@

  • Standards
  • Working Mode
  • Code of Conduct
    • +
  • FAQ

    • The WHATWG works on a number of technologies that are fundamental parts of the web platform. diff --git a/src/working-mode b/src/working-mode index 08633be85..1a4815f58 100644 --- a/src/working-mode +++ b/src/working-mode @@ -16,6 +16,7 @@

  • Standards
  • Working Mode
  • Code of Conduct
    • +
  • FAQ

    • Working Mode