-
Notifications
You must be signed in to change notification settings - Fork 39
/
index.html
1604 lines (1588 loc) · 76.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
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Modern Tooling</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c-common" async class="remove"></script>
<script class="remove">
var respecConfig = {
specStatus: "unofficial"
, shortName: "modern-tooling"
, editors: [{ name: "Robin Berjon", url: "http://berjon.com/",
company: "W3C", companyURL: "http://w3.org/" }]
, edDraftURI: "https://w3c.github.io/modern-tooling/"
, license: "w3c-software"
, repository: "w3c/modern-tooling"
};
</script>
</head>
<body>
<section id="abstract">
<p>
This document is meant to capture the state of the discussion about modernising the tooling
that supports the making of W3C standards.
</p>
<p>
Discussion is open to all. <a href="https://github.com/w3c/modern-tooling/">Pull requests</a>
are welcome, and the discussion takes place in
<a href="https://github.com/w3c/modern-tooling/issues">the issues</a>.
</p>
</section>
<section id="sotd">
<p>
This is just informal work by an informal task force.
</p>
</section>
<section>
<h2>Problem Statement</h2>
<p>
W3C is a heavily tooled organisation. We did Web tools long before they became ubiquitous
and our tooling has earned us two decades of praise — which is probably more than can be
said for any other part of the organisation.
</p>
<p>
But the Web has changed quite a fair bit since then. Today, tools abound. The Web is an
application platform. Our users are happy using many third-party tools, and it is only
natural that they will compare what they can find elsewhere to our offering, sometimes
preferring other options.
</p>
<p>
This causes problems:
</p>
<ul>
<li>
Our users move their work to third-party tools, where the data they produce in developing
specifications may be lost or locked up. GitHub is a primary example here.
</li>
<li>
The work that groups carry out is becoming increasingly scattered across services, such
that it is hard to track and hard to join. Issue tracking for instance is all over the
place.
</li>
<li>
Our tools, even when they work well and remain the preferred option, are starting to look
old in both styling and interaction style. It is hard for our users to maintain the
impression that they are building the Web of tomorrow while using tools that are clearly
from the 90s. Some of our more recent users even find them hard to understand. A good
example is <acronym title="Web-Based Straw-poll and balloting system">WBS</acronym> (here
is <a href="https://github.com/w3c/wbs-design">an early project to improve that</a>) or
the mailing list archives.
</li>
<li>
Accumulation is hard to manage and makes content hard to find. The W3C Web site and the
majority of its services are exposed essentially as one single entity. After twenty years
of accretion, that makes it hard to evolve as was made obvious in the recent discussion
about upgrading it all to HTTPS. The heavily granular usage of ACLs makes it essentially
impossible to index. Finding things on the W3C Web site typically involves knowing someone
with the URL equivalent of an eidetic memory and asking them where to go. This issue is
further compounded by user-hostile URL policies (datedspace). A good example here would
be trying to find the next-generation pubrules service.
</li>
</ul>
<p>
We need an energetic rethink of the W3C’s tooling in order to stay relevant to our users.
That is what this document endeavours to provide.
</p>
<section>
<h2>The Plan</h2>
<p>
I expect to proceed as follows:
</p>
<ul>
<li>
Iterate over this document through
<a href="https://github.com/w3c/modern-tooling/issues">issues</a> and
<a href="https://github.com/w3c/modern-tooling/">pull requests</a>. All discussions are
intended to be public.
</li>
<li>
Go broad and assume it’s Christmas. I don’t want to discourage input by having people
think about constraints. It’s of course very likely that at the end we can’t get
everything but that’s okay. We can easily prioritise later, but I don’t want to miss a
good idea.
</li>
<li>
Assume hackability. Even with the best and the pithiest involved in drafting this
document it is a given that not everything that may be useful to some part of our
community at some moment of the future will be thought of. We need to build to ensure
that our users can refine and extend our work.
</li>
<li>
Be particularly wary of the
<a href="http://en.wikipedia.org/wiki/Gal%C3%A1pagos_syndrome">Galápagos syndrome</a>
(Note for PLH: this is a variant of the NIH Syndrome, but more focused on how things
develop differently when somewhat isolated from the outside world, instead of simply
from distaste for others’ inventions). There is every reason for W3C to have its
specificities, even its quirks, but they need to be usable and manageable.
</li>
<li>
Target mid-April for a first draft for internal W3C discussion; then present an overview
to the AC at its early May meeting.
</li>
<li>
Hopefully start implementing!
</li>
</ul>
</section>
</section>
<section>
<h2>Executive Summary & Plan</h2>
<p>
While precise details about the manner in which our various tools could be improved were
deliberately kept out of this document, there are nevertheless <em>many</em> things that
people would like to see changed, improved, or added. As a result, the full list in the
following sections is long, and it is easy to get one’s eyes off the ball.
</p>
<p>
This section provides information on the projects that have been deemed high priority. These
are described at a high level, and resource estimates are provided for them. «First
priority» projects are intended for immediate development, «Second priority» projects are
expected to come in a second wave. Everything in this document not listed as part of those
two categories is considered to be kept for later. Note that «later» is not a fancy word for
«never», and people interested in jump-starting those should of course jump right to it. It
simply means that they are not immediately planned for with the resources available for the
execution of this plan.
</p>
<p>
Everything includes documentation and testing. All projects are expected to use continuous
development, which is to say that whenever something hits the <code>master</code> branch it
is deployed into production.
</p>
<section>
<h2>First Priority</h2>
<p>
The projects in this category include:
</p>
<dl>
<dt>Provisioning a machine</dt>
<dd>
<p>
This is required for development and beta-testing purposes.
</p>
<p class="est">
<strong>Estimate</strong>: Personal server will be used for testing, done.
</p>
</dd>
<dt>Unified Feed</dt>
<dd>
<p>
The goal of this project is to develop a service that can integrate all of the
information being produced as we work (as it happens) and expose it for querying. It
is the foundational brick for the dashboard, the notifiers, and possibly other
services.
</p>
<p class="est">
<strong>Estimate</strong>: 1 month FTE.
</p>
</dd>
<dt>Dashboard</dt>
<dd>
<p>
A configurable dashboard exposing the information that a given user wants to have.
This is necessary in order for people not to be lost anymore. This is intended to
evolve towards a full-fledged control panel for our users, but in the first pass the
primary goal is to make it work as a configurable information-access system.
</p>
<p class="est">
<strong>Estimate</strong>: 1 month FTE.
</p>
</dd>
<dt>Email Notifier</dt>
<dd>
<p>
This system plugs into the unified feed and send emails to specific targets for a
filtered subset of events.
</p>
<p class="est">
<strong>Estimate</strong>: At most a couple days’ work.
</p>
</dd>
<dt>IRC Notifier</dt>
<dd>
<p>
Same as the email notifier, but for IRC channels. Note that this could be demoted to
lower priority.
</p>
<p class="est">
<strong>Estimate</strong>: 2 weeks FTE
</p>
</dd>
<dt>GitHub Backup</dt>
<dd>
<p>
As more of our work transitions to GitHub, we need to maintain a backup of the
information we have there. The unified feed already effectively backs up information
from issues and the such, but the actual git content needs to be backed up as it
changes.
</p>
<p class="est">
<strong>Estimate</strong>: 1 week
</p>
</dd>
<dt>Echidna Notifications</dt>
<dd>
<p>
Echidna needs to send the information that it processes to the unified feed.
</p>
<p class="est">
<strong>Estimate</strong>: At most a few days’ work.
</p>
</dd>
<dt>W3C Data API</dt>
<dd>
<p>
This project is already under way, as such it is not specifically part of the Modern
Tooling effort. It is, however, important to have it available in time for some of
projects currently listed in «Priority Two».
</p>
<p class="est">
<strong>Estimate</strong>: 0 (already accounted for).
</p>
</dd>
<dt>Moving Discourse</dt>
<dd>
<p>
We already have an experimental installation of Discourse, but we want to move it to
WebPlatform. This is essentially: reinstalling, exporting the data, redirecting.
</p>
<p class="est">
<strong>Estimate</strong>: 0 (turns out it will already be done)
</p>
</dd>
<dt>Group Pages</dt>
<dd>
<p>
The manner in which groups manage their own pages today is appalling. The goal of this
project is to provide common infrastructure for them to be able to start reporting
on their work effectively. This has the added benefit that it can expose information
from groups straight to the unified feed (and then in turn to the dashboard).
</p>
<p class="est">
<strong>Estimate</strong>: 1 month FTE.
</p>
</dd>
<dt>Developer landing page</dt>
<dd>
<p>
This is already in progress. It essentially requires some tweaking and then deployment
at a decent URL. It should not have to block on things like donations; as soon as the
content is good we can ship it, and then iterate as more information and functionality
become available.
</p>
<p class="est">
<strong>Estimate</strong>: 10 days FTE.
</p>
</dd>
<dt>Guides So Far</dt>
<dd>
<p>
A general guide for the usage of GitHub, as well as guides for the tools listed in
this category (including Echidna) need to be written.
</p>
<p class="est">
<strong>Estimate</strong>: 2-3 weeks FTE.
</p>
</dd>
</dl>
</section>
<section>
<h2>Second Priority</h2>
<p>
The projects in this category include:
</p>
<dl>
<dt>Mailing List UI</dt>
<dd>
<p>
The goal of this project is to make the user interface for mailing lists more usable.
</p>
<p class="est">
<strong>Estimate</strong>: 2-3 months FTE.
</p>
</dd>
<dt>Interactivity in Specifications</dt>
<dd>
<p>
Our specification could suffer to make use of modern capabilities standardised across
the board (rather than added in an ad hoc fashion here and there).
</p>
<p class="est">
<strong>Estimate</strong>: 3 weeks FTE.
</p>
</dd>
<dt>Live Examples in Specifications</dt>
<dd>
<p>
The ability to have live examples that can be experimented with directly in the
specification would help make things much easier to understand for readers.
</p>
<p class="est">
<strong>Estimate</strong>: 2 weeks FTE.
</p>
</dd>
<dt>WebIDL Checker Integration</dt>
<dd>
<p>
The current WebIDL checker works, but it should be integrated into Specberus.
</p>
<p class="est">
<strong>Estimate</strong>: 1 week FTE.
</p>
</dd>
<dt>Easier GitHub Management</dt>
<dd>
<p>
A number of GitHub maintenance tasks are pretty repetitive and could be partially
automated. Also, templates to set up repositories would help people get it right and
not have to learn tricks from the lore.
</p>
<p class="est">
<strong>Estimate</strong>: 3 weeks FTE.
</p>
</dd>
<dt>Open Source Specification Styles</dt>
<dd>
<p>
Many people want to improve our specification styles, but «Big Bang» attempts to
change them entirely have so far failed. The goal of this project is to make the
styles open source in order to make it possible for people to contribute to gradual
improvements.
</p>
<p class="est">
<strong>Estimate</strong>: 2 weeks FTE.
</p>
</dd>
<dt>Etherpad</dt>
<dd>
<p>
Etherpads are very useful for collaboration, yet W3C does not offer one. As a result,
people use pads all over the place. This project simply installs an instance of our
own. The first step is to figure out which one is the best option.
</p>
<p class="est">
<strong>Estimate</strong>: @@systeam (will be estimated later, ongoing discussion).
</p>
</dd>
<dt>Collaborators Access</dt>
<dd>
<p>
We regularly need to provide some degree of access to some trusted collaborators. The
primary use case is the Web Platform Tests system where we have external developers.
This could simply be no more than putting <code>grumple</code> outside the firewall
and granting access to two or three people. This also needs a clear policy.
</p>
<p class="est">
<strong>Estimate</strong>: @@ted (the most urgent item already done, may not require
more).
</p>
</dd>
</dl>
</section>
</section>
<section>
<h2>Stakeholders</h2>
<p>There are multiple stakeholders with varying needs when it comes to tooling.</p>
<section>
<h2>AC Reps</h2>
<p>AC Reps represent W3C members within W3C, and, in a sense, W3C activities within their own companies.</p>
<p>
Their requirements include tools that provide a good overview of
their organization's activity in different sectors,
their administrative duties,
and legal aspects.
</p>
</section>
<section>
<h2>Group Chairs</h2>
<p>…</p>
</section>
<section>
<h2>Spec Editors</h2>
<p>…</p>
</section>
<section>
<h2>Other WG Members</h2>
<p>…</p>
</section>
<section>
<h2>Implementors</h2>
<p>…</p>
</section>
<section>
<h2>Developers (aka Authors)</h2>
<p>…</p>
</section>
<section>
<h2>W3C staff</h2>
<p>…</p>
</section>
<section>
<h2>End Users</h2>
<p>…</p>
</section>
</section>
<section>
<h2>Tools & Supporting Setup</h2>
<p>
This section is a categorised but unprioritised list of tools and services that W3C should
deploy, as well as ideas on how to manage integration with third-party systems.
</p>
<section>
<h2>Specification Development</h2>
<p>
The heart of what we produce is specifications, as a manifestation of consensus. These
already have some tooling support but it can be both further and better integrated or
documented.
</p>
<section>
<h2>Automatic Publishing</h2>
<p>
Great progress has already been made thanks to the
<a href="https://github.com/w3c/echidna">Echidna</a> system that can publish Working
Drafts in an automated manner, as often as needed. This can effectively make TR
documents and Editor’s Drafts indistinguishable.
</p>
<p>
There are, however, still a number of exceptions to the documents that Echidna can
publish, and a number of rough edges to the system itself and its documentation. It
needs iterative improvements.
</p>
<p>
It will also need to expose a stream of notifications (as described further below) for
the documents it publishes.
</p>
</section>
<section>
<h2>De Facto GitHub</h2>
<p>
While the door needs to remain open for alternatives that our users may wish to avail
themselves of, the expected default location for specifications (and any other
W3C-related repository) should be GitHub, preferably under the
<a href="https://github.com/w3c/">w3c</a> organisation. This has several implications.
</p>
<p>
We need to <strong>document the proper usage of GitHub for such work</strong>. Some of
our users who are not from the Web development community can at times struggle with the
site or with common conventions. Team resources need to be dedicated to supporting
users of GitHub. A specific collaboration with GitHub may be considered if needed.
<strong>NOTE</strong>: a <a href="https://github.com/w3c/using-github">repository</a>
has been created precisely to work on this aspect.
</p>
<p>
Better even than documentation, which is often ignored, a <strong>tool that enables the
Team and the Chairs to set up new repositories correctly</strong>, within conventions,
and given a few specific options would be most useful.
</p>
<p>
Groups regularly need to add new contributors to their repositories (or, on occasion, to
remove them); which requires administrative powers. Sadly, the granularity of the ACL
system there does not allow us to grant that power to non-Team participants, which in
turn means that the Team needs to be called upon for everyday business. An interface to
<strong>grant our users the ability to maintain a repository’s collaborators</strong>
without involving the Team would be a time-saver. The ability to activate Travis without
admin powers would also come in handy and save the Team some time.
</p>
<p>
Naturally, GitHub could disappear, go bankrupt, be overtaken by an evil gang of mole
rats, or simply fall behind. In such an event, we must have all the useful data at hand
and, if possible, be able to exploit it elsewhere. Git certainly makes it easy to keep
repository data — it only needs be cloned.
</p>
<p>
But GitHub also has a lot of useful information that isn’t in git: issues, discussions,
etc. We also need to keep that around. For that, we need a <strong>GitHub backup
tool</strong>. This would use git’s naturally distributed nature in conjunction with the
ability to receive organisation-wide hooks (and use the API to grab everything) in order
to store all the useful information. Ideally all work would happen under the
<a href="https://github.com/w3c/">w3c</a> organisation but the tool ought to be flexible
enough to account for there being work elsewhere.
</p>
<p>
The hook system should also be used so as to produce a stream of notifications that can
later be integrated into the dashboard.
</p>
<p>
This also entails that both <code>dev.w3</code> and <code>dvcs.w3</code> should be phased
out. No new repository should be created there and no new user granted access. Projects
that are still active there should be moved (and redirected). Obviously the content
already published that no one is touching will likely need to stay there, but it should
essentially be a static, frozen archive of old work.
</p>
</section>
<section>
<h2>Specification Styles as a Community Project</h2>
<p>
We regularly hear complaints about the usability of our specification styles. Several
projects were started to radically improve them, but petered out.
</p>
<p>
At the same time, they cannot be changed radically overnight. Older specifications
cannot be broken through style changes and we shouldn’t throw away the brand recognition
that comes with the current style.
</p>
<p>
The solution is to open up the management of these styles and drive the project through
largely small, incremental updates to the stylesheets. A repository for the styles
should be created and we should start accepting pull requests. At first a clean-up of
the current code ought to be carried out. Then, regular releases ought to be made
based on contributions.
</p>
</section>
<section>
<h2>Interactivity in Specifications</h2>
<p>
The Web is no longer a static medium that is essentially fluid print brought to the
screen. Documents today can work with the user interactively. So far we have only very
sporadically made use of these capabilities, when in fact they could greatly enhance the
usage of our primary products.
</p>
<p>
A common library should be developed to provide basic functionality across all
specifications. This would include:
</p>
<ul>
<li>
Simple, streamlined bug reports from within the document, with anchor and selected
text included.
</li>
<li>Easy linking to sections.</li>
<li>Finding for each definition where it is used.</li>
<li>Page-width and boilerplate visibility configurability.</li>
<li>Integration with testing & coverage results.</li>
<li>Integration with existing issues lists.</li>
<li>
Tabs offering different views of content (e.g. several serialisations of a given data
model).
</li>
</ul>
<p>
Like the styling project, this can easily start small and humble, and progressively grow
into a highly useful system thanks to contributions.
</p>
</section>
<section>
<h2>Document Structure Beyond PubRules</h2>
<p>
The <a href="http://www.w3.org/2014/10/pubrules/">new PubRules</a> system
(<a href="https://github.com/w3c/specberus">Specberus</a>) is a welcome improvement in
the toolbox. It still needs some UI fixes and should be moved to a location not intended
to make it impossible to find, but overall it should soon be able to replace the previous
instantiation.
</p>
<p>
We should, however, think beyond specification validation. As things stand today, it is
extremely hard to get information out of our documents. Even when they are correct, they
are all different. The RDF export is a very partial view and borderline unusable. The
data that is extracted into W3C’s systems cannot be obtained, and is partial as well.
Yet so much could be done with this information.
</p>
<p>
We need to progressively refine the <em>components</em> that make up a specification and
to rethink them using modern HTML constructs for document semantics and metadata. Step
by step we need to start unifying these constructs across the board (having tools
produce them and enforcing them through PubRules). Document structure and metadata need
to become eventually regular enough that TR can be used as an API.
</p>
</section>
<section>
<h2>Specification Production Tools</h2>
<p>
We have quality specification production tools and most specifications today make use of
them. It is worth thinking about how, as a common ecosystem, they can be improved.
</p>
<p>
One aspect in which they can be improved is to bring their source formats in line
wherever it makes sense (and isn’t disruptive). The end goal here is that contributors
to specifications who move between groups should as much as possible find themselves
able to switch between tools as easily as possible.
</p>
<p>
This, naturally, should not be done at the cost of innovation in those tools, but it
surely can be done for some of the common, well-understood aspects.
</p>
</section>
<section>
<h2>Cross-References Support</h2>
<p>
The Web platform is increasingly described by a large mesh of specifications that
reference one another. Currently, this is done relatively poorly overall. There are
several methods in use:
</p>
<ul>
<li>
Handwave about doing something the way another specification says to do it, with a
reference to the whole document.
</li>
<li>
Link to a definition in another specification, which can break (as has happened
several times for people referencing HTML), and sometimes forget to include a formal
reference.
</li>
<li>
List imported definitions from other specifications, with links and references, and
then use internal references to those. This is likely the best option available today,
but it is cumbersome work.
</li>
</ul>
<p>
Ideally, all definitions from all specifications should be globally available. This
would make it possible to simply reference them in a specification tool source format
and get the correct link and reference handled. It would enable the generation of
glossaries. (We urgently need to phase out <a href="http://www.w3.org/2003/glossary/">the
current one</a>.) We could expose a searchable interface that would make it possible for
people to find which specification defines what, and which make use of what concept or
construct (something that would prove invaluable in coordination).
</p>
</section>
<section>
<h2>Live Examples</h2>
<p>
It is extremely common today to replace examples in documentation with live ones that
can be edited and rendered using one of the many services that provide such
functionality.
</p>
<p>
While it is probably not acceptable to inject code from a third-party service into our
specifications, there exist reusable components that would enable examples
in our specifications to become hackable. This would have tremendous
value for developers trying to learn and understand the technology.
</p>
</section>
<section>
<h2>Specref</h2>
<p>
<a href="http://www.specref.org/">Specref</a> is the database of
bibliographical references that specifications rely upon. It has been through several
iterations and is generally considered good, but it can be improved.
</p>
<p>
Currently managed by Tobie, it could be brought under W3C management.
</p>
<p>
It could use a front-end for adding resources and a few other niceties to integrate
it better with the W3C tool suite (e.g., improving Marcos’
[bibliography generator](http://marcoscaceres.github.io/bib_entry_maker/)).
</p>
</section>
<section>
<h2>Specification Quality Checker (CI)</h2>
<p>
Some specification issues (that are not about the actual prose content) can sometimes
exist for embarrassingly long periods of time before anyone notices. Sometimes they are
noticed after a document is finalised. Or they are raised at the worst moment, all at
once when the editor is busy doing something else.
</p>
<p>
Developers use continuous integration to make sure that there is a constant pressure
towards quality rather than a last-minute rush — so should editors. There have been
experiments around this (using Travis’ integration with GitHub); they should be
expanded and systematised.
</p>
<p>
Ideally, an editor should be able to, at the click of a button, have the proper Travis
integration (and dependencies) installed into the specification’s repository and
deployed for immediate usage. This could even be made the default at repository creation
if it is known that it will contain a specification.
</p>
<p>
Several different tools can be called upon for quality checking; since they can be used
on their own they are listed separately below and in the «Developer Tools» section.
</p>
</section>
<section>
<h2>WebIDL Checker</h2>
<p>
We have an existing WebIDL Checker. It needs to be integrated into the quality workflow
(arguably into Specberus as well as into the linting options of specification tools),
exist with guarantees of maintenance, documentation, and made easy to find.
</p>
</section>
<section>
<h2>References Checker</h2>
<p>
We have existing tools (that almost no one knows about) that can read a specification
and validate that its references (at least to W3C or IETF documents) are up to date with
the latest versions of those documents: the
<a href="http://www.w3.org/2004/07/references-checker-ui">references checker</a> and the
<a href="http://www.w3.org/2007/05/ietf-references-checker">IETF references checker</a>.
</p>
<p>
While specification production tools, by building atop SpecRef, have largely removed the
need for these, some specifications are produced by hand and some have local
bibliographies. They should be part of automated checking.
</p>
</section>
<section>
<h2>Spell Checker</h2>
<p>
W3C actually exposes a <a href="http://www.w3.org/2002/01/spellchecker">Spell checker</a>
tool (that can work with HTML). It is unclear that this could be integrated into
automated checking (given the number of justifiable exceptions) but it could perhaps be
made more prominent (or, if found not to be useful, retired).
</p>
</section>
<section>
<h2>Specification Diffs</h2>
<p>
W3C currently offers an <a href="http://www.w3.org/2007/10/htmldiff">HTML Diff</a>
service which is sometimes used to see changes to documents.
</p>
<p>
It is a common request to find out what has changed between two versions of a
specification. In fact, producing a diff seems slated to be part of the new errata
management approach that the AB is investigating.
</p>
<p>
This should be made automatic, and possibly specialised. Right now the HTML diff tool
will produce as output a complete document, which can make the differences hard to find
(e.g. a paragraph change in the whole HTML specification). It can also include a lot of
spurious differences. (For instance, if a section was added at the beginning, all the
section numbers come out as changes.)
</p>
<p>
This tool could be specialised for specifications in such a way that ignorable
differences would be ignored. Also, an affordance could be exposed in specifications
offering to show a diff between the version being looked at and any other version of that
document.
</p>
</section>
<section>
<h2>Dependency Tracker</h2>
<p>
Specs depends on one another, but there is very little done to ensure these dependencies
are kept in sync; they are expected to be reviewed at transitions, and sometimes the
link checker will spot a dependency gone wrong, but a more systematic approach would
allow for better coordination across groups and reduce the risks for «monkey patching».
</p>
<p>
A dependency tracker that would allow to visualise and report the dependencies between
specs, e.g. in terms of WebIDL interfaces but also in terms of algorithms, would be
terrific. Ideally, they would lead to much more granular dependencies — a spec usually
depends on a few items of a given spec, not the whole thing; assessing dependencies at
the right granularity would be helpful for streamlining transitions on the
Recommendation track.
</p>
</section>
<section>
<h2>WYSIWYG Specifications</h2>
<p>
Supporting WYSIWYG editing for specifications could help improve collaboration and
contributions from people who might know HTML but are not necessarily versed in the
specific formalism of a given specification tool.
</p>
<p>
While such a tool would be interesting and valuable, it is a long and complex project
to put together, and likely not a priority.
</p>
</section>
</section>
<section>
<h2>Dashboard</h2>
<p>
Perhaps the most common complaint about the W3C’s tooling setup, which is only made worse
by spreading work across a broad set of external services, is that there are too many
places at which to track things, often in very different ways.
</p>
<p>
In addition to tracking information, taking action within the system also involves
remembering where different parts are. There are several pages listing services (e.g.
the Member page, the AC page, the Editors’ page) but they can prove overwhelming,
especially since they often have content that is out of date. They are also very generic:
most users don’t need to know everything that they contain.
</p>
<p>
This leads to three high-level requirements for a modern system, from its users’ point of
view:
</p>
<ul>
<li>
<strong>Unity</strong>: there needs to be a single URL at which to find
<em>everything</em>. This should include information about what is going on in parts of
the organisation that one is interested in, but also the ability to use the tools that
one needs to carry out one’s work within W3C.
</li>
<li>
<strong>Customisability</strong>: since no two participants have the same needs, they
need to be able to fully customise their interface.
</li>
<li>
<strong>Consistency</strong>: learning one tool is difficult, learning many all the more
so if they all look different. As far as possible we should endeavour to expose a
consistent user experience to our systems so as to reduce the learning curve for
newcomers.
</li>
</ul>
<p>
This translates to a specific design for the various moving parts of the system.
</p>
<section>
<h2>Unified Feeds</h2>
<p>
There are many sources of data that can become involved in the dashboard. In order to
keep them manageable, we need a specialised component that can provide a consistent
interface to them.
</p>
<p>
This service is a relatively simple shell around various data streams. It can be
configured to poll a resource at regular intervals (e.g. retrieve and process an RSS
feed), or on the contrary to expose a hook for pushed information (e.g. we can set up
a GitHub hook calling it for all events in the <code>w3c</code> organisation there).
Ideally we could also collect data from mailing lists, for instance to produce a feed of
browser vendors’ intents to implement/deprecate.
</p>
<p>
Each of its plugins knows how to obtain data and store it in a unified manner. They can
easily be configured (e.g. to add RSS feeds, to receive GitHub notifications from other
repositories).
</p>
<p>
This mass of data can then be returned to queries that essentially involve two filters:
which feeds the user is interested in, and a date-time cut-off so that one can ask only
for what has happened since one last visited.
</p>
<p>
Additionally, a WebSockets interface can be made available so that dashboard users can
get notifications in real time in the UI.
</p>
</section>
<section>
<h2>Dashboard</h2>
<p>
The dashboard itself is nothing but a container of smaller widgets which can be
configured, added, or removed by each user. In order to be fully generic, we need to
ensure that it remains extremely simple both in its own functionality and in the
interface it exposes to widgets.
</p>
<p>
Widgets can be used as part of an overview grid, or can take over the whole screen when
they need more real estate.
</p>
<p>
It is very important that it be possible for independent contributors to develop widgets
separately, that can then become available through the dashboard (after W3C approval, we
can’t automatically deploy third-party code). Widgets can expect to run in insulated
<code>iframe</code>s and to communicate with the dashboard to access whatever
information they need through messaging.
</p>
<p>
W3C’s own applications are expected to transition to being exposed as widgets. The
general principle at work is that services should be made available as APIs, and
exposed to users through widgets. With this in mind widgets can use a common stylesheet
and common scripting libraries to help support greater coherence and fluidity in
interaction.
</p>
</section>
<section>
<h2>Notifiers</h2>
<p>
Another tool that can plug into the unified feed is a notifier. Users can opt into
being notified of various events by email (through, you guessed it, a dashboard widget).
Likewise, IRC channels can be notified of specific events by a bot. The idea is that
this is extensible: the unified feed provides the data in a usage-agnostic manner; tools
then piggy-back on it.
</p>
<p>
The notifier simply receives the unified data feed, and for each event finds if there
are people who want to be notified of it. If so, they get an email.
</p>
<p>
The notifier needs to be able to filter events based on labels. For instance, the I18N
WG uses «I18N» labels on bugs on other groups’ bugs trackers in order to track
horizontal reviews. Similar conventions could be supported by other groups.
</p>
<p>
Dom has built a tool
(<a href="https://github.com/dontcallmedom/github-notify-ml">github-notify-ml</a>) that
can notify mailing lists when certain events happen on GitHub. It could be enhanced to
make use of this system.
</p>
<p>
It would prove particularly useful if the notifier were able to filter events to match
changes to specific sections of a specification (notably to help horizontal reviewers).
</p>
</section>
</section>
<section>
<h2>Groups & Community</h2>
<p>
This section covers tools that are in common use for coordination and communication inside
groups and the broader community.
</p>
<section>
<h2>IRC & Chatting</h2>
<p>
IRC is relatively operational and it is highly programmable. Because of this, it would
be hard to replace with other more modern solutions such as
<a href="https://slack.com/">Slack</a> or <a href="https://gitter.im/">gitter</a>. It
is, however, often unknown to the younger generation or in fact more generally to people
not strongly steeped in the open source culture of the past twenty years. As such, an
improved Web interface would be desirable. (The current one is serviceable, but could do
with some freshening.) One potential option here would be
<a href="https://github.com/erming/shout">Shout</a>. It is a client-server combo with a
rich interface, and is entirely implemented in JS. Amongst its advantages are that it
can remain connected to IRC even when you close your browser, it supports connecting as
the same user through multiple channels at once, and it has a responsive layout that is
well-suited to usage on a smartphone.
</p>
<p>
IRC logging could, however, be improved. <code>RRSAgent</code> has its value for the
specific case of capturing minutes in a manner that is easily reused by other tools, but
as a general-purpose logger we can do better. Too many channels are simply not logged at
all — even though much work takes place over IRC! And when they are logged,
<code>RRSAgent</code> logs are then extremely hard to find; lost in dated-space never to
be retrieved again.
</p>
<p>
A general-purpose channel logger bot need not be complicated. In my experience, people
are satisfied with <a href="http://krijnhoetmer.nl/irc-logs/">Krijn Hoetmer’s setup</a>.
Its limitations are largely that it requires getting agreement from Krijn in order to
get something logged, and it wouldn’t scale to the many channels we would want to log.
The RICG also uses a simple <a href="https://www.drupal.org/project/bot">Drupal-based PHP setup</a>
to reference discussion, retrive to GitHub issue information, and for minute-taking.
</p>
<p>
A single service at which all chat logs can be located would therefore be needed. It
does not require bells and whistles, but it needs to support continuous logging, finding
channels, and search.
</p>
</section>
<section>
<h2>Mailing List Interfaces</h2>
<p>
While the mailing list service itself is largely beyond reproach, the interface to our
archives is now one of the more decried parts of our offering. While a number of the
complaints may be exaggerated, it is certainly true that it could do with
<a href="https://github.com/w3c/mailing-list-archives">improvements in both style and
usability</a>.
</p>
<p>
A project that is commonly cited as a huge improvement over what existed previously is
<a href="https://esdiscuss.org/">https://esdiscuss.org/</a>. It is not perfect, and the
source can probably not be reused as is. Its fundamental architecture is sound however:
convert email to JSON and expose those for other services to build upon. Given the size
of the W3C archive and its daily volume, this would not be a minor undertaking — it is
likely better to test-drive the idea on a small set of lists.
</p>
<p>
People have also complained about the user experience of signing up to our lists. A
user interface allowing people who have an account (either with us, or with a
third-party service that we can authenticate against) to use that to subscribe directly
(without the email ping-pong) and to immediately accept archival would help our
community as well.
</p>
</section>
<section>
<h2>Forum</h2>
<p>
Forums have overtaken mailing lists in terms of popularity for online discussion. Groups
would certainly benefit from being able to rely on those for at least some of their
work.
</p>
<p>
This aspect is already covered by our
<a href="http://discourse.specifiction.org/">Discourse</a> installation, which is being
moved to WebPlatform.
</p>
</section>
<section>
<h2>EtherPads</h2>
<p>
Etherpads are commonly used to take shared notes, which <em>could</em> be useful for
minutes in some groups, but is also particularly useful during brainstorming sessions
when a group of people wishes to collectively.