A spec style/structure checklist?

[slightlyoff]

In discussion with @ r12a, it seemed like many groups doing reviews of specs would benefit from better guidance to spec authors about how to structure their documents and design docs / explainers. Is this something we have the appetite to produce?

[mnot]

I'm a bit concerned that it could quickly become overly bureaucratic if it's a document that we drop onto people. I could see giving people advice / mentoring about how to approach documents upon request, and maybe eventually distilling a few bits of advice from that.

[marcoscaceres]

I'd love to have something rough to drop into:
https://github.com/WICG/starter-kit/blob/master/templates/explainer.md

Just simple/human things to put in there (i.e., keep this targeted at developers) - and maybe just some links to what we consider good examples of an explainer (e.g., the SW one).

[dwsinger]

On Sep 22, 2016, at 1:43 , Marcos Cáceres notifications@github.com wrote:

I'd love to have something rough to drop into:
https://github.com/WICG/starter-kit/blob/master/templates/explainer.md

Just simple/human things to put in there (i.e., keep this targeted at developers) - and maybe just some links to what we consider good examples of an explainer (e.g., the SW one).

Do we have an ‘empty skeleton’ or template that we maintain, that we can point people at?

Also, the AB is concerned that the /TR page is an un-navigable list (‘graveyard’ has been used). Templates or other work that help classify specs (some semantic tagging) might help.

I like templates, as they could include sections which are not uniformly present — how to report an issue and how to see reports of issues; security and privacy considerations; and so on

David Singer
Manager, Software Standards, Apple Inc.

[marcoscaceres]

Do we have an ‘empty skeleton’ or template that we maintain, that we can point people at?

The WICG starter kit includes a ReSpec and BikeShed template... which point to helpful guides produced by the TAG (the API design guide, and the guide on specs that make use of promises).

https://github.com/WICG/starter-kit/tree/master/templates

As I'm not a spec novice, I'm not in a position to judge if those are good or not - so feedback welcome if they should be improved.

Also, the AB is concerned that the /TR page is an un-navigable list (‘graveyard’ has been used). Templates or other work that help classify specs (some semantic tagging) might help.

Could you kindly clarify what you mean by "semantic tagging"?

I like templates, as they could include sections which are not uniformly present — how to report an issue and how to see reports of issues; security and privacy considerations; and so on

BikeShed and ReSpec's templates include links to GitHub repos... and both processors get upset if you don't have security and privacy considerations sections.

[dwsinger]

On Sep 26, 2016, at 2:28 , Marcos Cáceres notifications@github.com wrote:

Also, the AB is concerned that the /TR page is an un-navigable list (‘graveyard’ has been used). Templates or other work that help classify specs (some semantic tagging) might help.

Could you kindly clarify what you mean by "semantic tagging"?

I think there was an effort once to include keywords, RDFa and so on, to enable classification of specs. The TR page is an undifferentiated list of specs; I have a vague dream that one might be able to find (for example) all specs that talked about being an HTML extension, or about styling, or the DOM, and so on. It’s very vague.

We don’t do well at helping developers find stuff right now, and I am waffling about tagging as a possible way to help.

David Singer
Manager, Software Standards, Apple Inc.

[marcoscaceres]

@dwsinger, thanks for the clarification - I see what you mean. And yeah, having just had al look at TR for the first time in years - it's pretty terrible...

A good source of inspiration for organization might be something like: https://developer.mozilla.org/en-US/docs/Web

The above far from perfect - but it would be great for TR to at least remove all the dead stuff and focus on the central themes of HTML, CSS, JS Web APIs (Web Platform). And maybe a totally separate part for the "data" efforts - where all the X* things would go.

Having those things automatically organized might be a bit of an ask... but the W3C could just put that on GitHub and let the community help manage it.

[tobie]

W3C could just put that on GitHub and let the community help manage it.

Yes.

[plehegar]

had some discussion with @sideshowbarker about editor's training. Adding him into this loop.

[ylafon]

@deniak is also in the loop (now by reference)

[sideshowbarker]

had some discussion with @sideshowbarker about editor's training. Adding him into this loop.

I have nothing to add at this point other than to say, Yeah we need to produce some guidelines docs for spec editors in WGs (along with guidelines docs for test writers in WGs). I guess we (at least @plh and I) just need to put a more concrete plan/timeline behind it.

[tobie]

Let me repeat the same suggestions I made during the TPAC session on spec publishing:

1. We need a single point of entry for all things related to spec editing. From picking a tool to editing specs, to learning about RFC2119, to understanding process, pubrules, WebIDL, automated publishing, GitHub, etc. that is designed from the perspective of the editor and not from the perspective of whoever is maintaining these different tools. Right now, I'm supposed to know the difference between Echidna, Specrebus, and Pubrules. I've been around for years now and I'm still utterly confused.
2. Using GitHub Pages for this is ideal: the format uses markdown and Jekyll, two tools GitHub users have become intimately acquainted with, and contributing is a mere pull-request away. This is what we've done for Test the Web Forward, and three years later, it's still the go to place for learning about W3C testing.
3. You want to actively prune previous scattered content and either integrate it in this new system or remove it altogether: there must be one source of truth that everyone contributes too, not multiple as is currently the case.
4. This resource must belong to the community and W3C must only help make it happen. It shouldn't own it.
5. It might be a good idea to do a tiny bit of branding so the resource stands out.

[marcoscaceres]

Agree with @tobie regarding 1. There is a gross "trial by fire" culture wrt editing specifications around here that we need to root out. This will take time tho. I've had people complain at me that new contributors to the WICG don't know how to edit specs - like it's some magical thing that they should know how to do or that they should know all the magical binding behavior in WebIDL, etc.

Re: 3 - so much yes. But we need to make a decision there. Either gh-pages is the source of truth or TR is... and if TR is, then Echidna and Specrebus have got to get a lot more user friendly. It's not that those folks working on those have not done a great job - but like @tobie, it's just too inside baseball and still way too hard to use. I tried to fix that by writing the wiki pages that describe the process for using some of those... but it's still super confusing to auto-publish.

Re: 4... we had a false start at this once: https://github.com/specthewebforward ... even bought the domain (specthewebforward.org)... I think I let it lapse tho.

[dbaron]

QA Framework: Specification Guidelines might have some useful things here

[tobie]

@dbaron, that's over a decade old, though.

[dbaron]

Yes, but I've heard a bunch of positive feedback about it over the past decade (at least assuming it's the right document to point to, which I think it is).

[marcoscaceres]

I have fond memories of reading that document when I was starting out. IIRC, it really does cover the basics well.

The following post by Hixie was probably the most important thing I ever read about how specs should be written:

https://ln.hixie.ch/?start=1140242962&count=1

I also worked on this thing...

https://www.w3.org/TR/test-methodology/

there might be useful conceptual things in there.

[slightlyoff]

Per @marcoscaceres's request, working on a draft of an explainer outline (and guide) to drop into https://github.com/WICG/starter-kit/blob/master/templates/explainer.md. Scheduled for a future call to discuss.

[chaals]

@slightlyoff:

… working on a draft of an explainer outline (and guide) to drop into …

Where?

[slightlyoff]

@chaals: Draft explainer outline doc here (will be locked down shortly): https://docs.google.com/document/d/1cJs7GkdQolqOHns9k6v1UjCUb_LqTFVjZM-kc3TbNGI/edit#heading=h.27qen9z79dwm

@marcoscaceres: does ^^^ look like something you'd be willing to integrate into the WICG starter kit? Can PR for it if you like where it's headed. @triblondon has threatened to visit you in person later this week to get an update on your views. No word on wether or not he'll be bringing gin.

[torgo]

Some work left to be done here on a spec outline document.

[marcoscaceres]

@slightlyoff, would gladly take that! looks great.

[triblondon]

We created WICG/starter-kit#10. We're not realistically going to add any more to this, so closing.