-
Notifications
You must be signed in to change notification settings - Fork 3
/
index.html
236 lines (230 loc) · 11.7 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
<!DOCTYPE html><!--
WARNING!
Do not edit this file! (Unless you're editing the template which generates this comment :) as
it is autogenerated and will get overwritten. Edit the source documents under /content/ instead.
--><html lang="en"><head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Web Platform Specs</title>
<link rel="stylesheet" href="/docs/css/kraken.css">
<link href="/assets/img/icon.png" rel="shortcut icon">
</head>
<body>
<header>
<div class="subheader clearfix">
<a href="/docs/"><img src="/assets/img/logo.svg" width="100" height="100" alt="Web Platform Specs"></a>
<div class="title">
<h1>Web Platform Specs</h1>
<div class="subtitle">the kind, gentle, and fun place to make specs</div>
</div>
</div>
</header>
<nav>
<a href="/docs/">docs</a>
•
<a href="/docs/how-to/">how-to</a>
•
<a href="/docs/policy/principles.html">principles</a>
•
<a href="https://github.com/webspecs/docs">fork me</a>
</nav>
<div class="content"><p class="blurb">
<strong>Web developers</strong> create most of the Web’s magic, yet they are almost absent from the process of
creation of core Web technology. <strong>Web standards</strong> suffer sorely from Web developers’ absence; yet,
at this time, contributing to standards remains unnecessarily daunting.
<strong>Web Platform Specs</strong> — or “WebSpecs” for short — aims to progressively build up both the
technical solution and the community involvement to address this issue.
</p>
<div class="act">
<a href="/">
<span class="callout">Read</span>
There aren’t yet many existing specifications, but we’re building things up piece by piece.
</a>
<a href="/docs/how-to/discuss.html">
<span class="callout">Discuss</span>
We have a welcoming forum to which anyone can bring an idea that isn’t yet mature enough to
become a specification.
</a>
<a href="/docs/how-to/create.html">
<span class="callout">Create</span>
Specify new Web technology, either by proposing a change to an existing document or by
creating a new one from scratch.
</a>
</div>
<section id="wat">
<h2>What is this?</h2>
<p>
This project is not a replacement or a competitor but rather a complement to <a href="http://w3.org/">W3C</a>, <a href="https://whatwg.org/">WHATWG</a>, <a href="http://www.ecmascript.org/">TC-39</a>, the <a href="http://ietf.org/">IETF</a>, or
whichever standards organisation may be in charge of this or that bit of the platform. As
such, it is <em>emphatically not</em> an <a href="http://xkcd.com/927/"><code>xkcd:927</code></a> alternative to existing solutions.
</p>
<p>
Our idea is simple: this project provides a welcoming environment for anyone to contribute to
the creation and development of standards, using tools and workflows familiar to Web
developers. We take care to ensure that the legal requirements involved in contributing to
given standards are fulfilled without getting in the way. Then whatever dark magic is required
to get a document produced here published on a standard track within a given organisation does
not interfere with the fun work of creating Web standards.
</p>
<p>
Historically, standards discussions have often been plagued by negativity, distrust, and
stop-energy. The standards world is fraught with useless drama and what often looks like petty
turf wars. This drives away many would-be contributors since sane people rarely wish to endure
abuse for no good reason when all they want is to make the Web a better place.
</p>
<p>
That stops here.
</p>
<p>
In this project, we take friendly, constructive interactions very seriously and we take a
<em>very dim view</em> of invidious comments. If you notice unfriendly behaviour, please flag
it as such as it will not be tolerated. For more details, you can see our <a href="policy/anti-jerk.html">anti-jerk policy</a>.
</p>
</section>
<section id="status">
<h2>Current Status</h2>
<p>
The project is still in its early phase, there is much that has yet to be put into place,
but the adventurous can get started!
</p>
<p>
More specifically:
</p>
<ul>
<li>
The new specification style has started being used, and a small number of specifications are
being added to the <a href="/">Web Platform index page</a>. More are on their way!
</li>
<li>
<a href="http://discourse.specifiction.org/">Online discussion for proposals</a> works (it
will be migrated to a new location but the content will be kept).
</li>
<li>
The <a href="https://github.com/webspecs">GitHub organisation</a> is up and running, and you
can already jump in to help.
</li>
<li>Automatic publishing based off GitHub repositories is operational.</li>
<li>The documentation needs work, but is being written.</li>
<li>
Support tooling to create specifications is available, notably
<a href="https://github.com/webspecs/webspec">to create and validate specifications</a> and
to generate them using either <a href="https://github.com/webspecs/bikeshed">Bikeshed</a> or
<a href="http://w3.org/respec/">ReSpec</a>.
</li>
<li>
Our sister project <a href="https://github.com/w3c/web-platform-tests/">Web Platform
Tests</a> (backed by the <a href="http://testthewebforward.org/">Test The Web Forward</a>
events) is operational. It provides the testing infrastructure for Web Platform Specs.
</li>
</ul>
</section>
<section id="community">
<h2>Community & Support</h2>
<p>
Getting started can be a bit daunting. If you’re hesitant, or if you have any question, simply
either:
</p>
<ul>
<li>
Bring up your issue on <a href="http://discourse.specifiction.org/">Discourse</a>, there
are always helpful people there ready to give you a hand; or
</li>
<li>
Come hang out on IRC, channel <a href="irc://freenode.net/webspecs">#webspecs on the
Freenode.net network</a>, it’s a small gang of friendly people who’ll help you out; or
</li>
<li>
If all else fails, ping <a href="https://twitter.com/robinberjon">Robin</a> on Twitter and
he’ll figure something out.
</li>
</ul>
<p>
In any case, don’t be shy and don’t be scared! No one will bite your head off, and if they try
we’ll handle them, as per the <a href="policy/anti-jerk.html">anti-jerk policy</a>.
</p>
</section>
<section id="how-things-work">
<h2>How Things Work</h2>
<p>
If you really want to get involved you will want to read the more complete documentation
in the <a href="how-to/">how-to section</a>. But here’s the summary version.
</p>
<p>
For those simply interested in <strong>reading specifications and ongoing proposals</strong>,
they are <em>all</em> linked from the Web Platform Specs index at the root of <a href="/">https://specs.webplatform.org/</a>. You can see this as the one-stop-shop for all
specifications produced by this project. Eventually we are considering turning this into the
single entry point for all specifications that define the platform irrespective of where they
originate, but that is still under discussion.
</p>
<p>
If you wish to <strong>propose or discuss ideas</strong> that aren’t clearly bugs against a
specific document, then our <a href="https://discourse.org/">Discourse</a> instance at <a href="http://discourse.specifiction.org/">http://discourse.specifiction.org/</a> (no, it’s not
a typo and the address will change) is perfect for that. It already has an active community,
without being noisy either. If the mere words “online forum” are enough to fill you with the
sort of dread that only the combined power of terrible design and blinking emoticons can
raise, then fear not. We are like you. This specific forum is not like that. It is lovely to
use, pretty to look at, and discussions are eminently civilised.
</p>
<p>
Finally, for those wishing to <strong>work on an actual specification</strong> things are a
little bit more involved, but it’s very little you won’t be familiar with anyway if you’ve
done open source development.
</p>
<p>
Specifications are written using formats that are friendly to people who know Web technology
but aren’t necessarily standards experts. There are two options. If you prefer HTML and
JavaScript then <a href="http://w3.org/respec/">ReSpec</a> (see also
<a href="https://github.com/w3c/respec">the source</a>) is a popular option. The idea is that
you write straightforward HTML and this little JavaScript library handles all the stuff you
don't want to be thinking about for you. If you're more with the Markdown (or is it
CommonMark now?), or if you’re like Python, you can use the most excellent
<a href="https://github.com/webspecs/bikeshed">Bikeshed</a>, by the most excellent Tab Atkins.
Rooted in simple Markdown conventions, like ReSpec it takes care of a lot of the boring stuff
involved in specifications, such as cross-references, consistent styling, numbered sections
and tables of contents, and much, much more.
</p>
<p>
To file a bug against a specification, just do so in its GitHub repository (the link will be
at the top). If you wish to propose a relatively simple change, then simply make a pull
request, as usual. If however the change you are proposing is a little more involved and
would benefit from broader community review, then you will want to keep your fork separate
while it is discussed and for that to have it included in the index as a proposal. That’s
straightforward: it’s a simple matter of making a pull request against
<a href="https://github.com/webspecs/the-index">the index</a> to include a link to your
proposal, using a very simple format.
</p>
<p>
In order to start a specification from scratch, the process is just about the same. You need
to create a repository of your own (it does not have to be under the “webspecs” organisation),
being careful to give it a sensible name as that is what will be used to identify it in the
system. We recommend that you use the <a href="https://github.com/webspecs/webspec"><code>webspec</code></a> tool to make sure that it
is set up properly. Once you’ve written up enough that you would consider sharing it with the
world, simply make a pull request to have it linked to from
<a href="https://github.com/webspecs/the-index">the index</a>.
</p>
<p>
That’s it! Or at least, that’s all you need to understand to get started. We are building
extensive documentation. And like everything we do, if you don’t like it,
<a href="https://github.com/webspecs/docs">fork it and send us a pull request</a>!
</p>
<p>
Enjoy the ride!
</p>
</section>
</div>
<footer>
<div class="subfooter">
<p>
<a href="/">specs</a>
•
<a href="http://www.w3.org/Consortium/Legal/copyright-software" rel="license">license</a>
•
<a href="https://github.com/webspecs/docs">fork me</a>
•
<a href="/docs/policy/principles.html">principles</a>
•
<a href="/docs/policy/anti-jerk.html">anti-jerk policy</a>
</p>
</div>
</footer>
</body></html>