ReSpec and how it gets used

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
21 messages Options
12
Reply | Threaded
Open this post in threaded view
|

ReSpec and how it gets used

Shane McCarron-6
As one of the ReSpec maintainers, I am often concerned that changes we make to the implementation will break stuff.  And given some recent events, I think that concern is merited.

One question that keeps coming up is "how is ReSpec used?"  Is it only used by document editors and the publication system, is it also used by the working groups and reviewers (in that they are looking at live documents), or is it used even more broadly?

We know that ReSpec is used by communities outside of the W3C, for example.

My basic concern can be characterized as "if we start using [insert new cool browser feature] in ReSpec, will our constituents still be able to use ReSpec?"  Or, to turn that around, "Are there people using ancient user agents actively accessing live documents written with ReSpec?"

So, a few questions for the group:
  1. Do you have a feel for how ReSpec is being used?
  2. Is there a policy about how far "back" we need to continue supporting user agents?
  3. Is there a way we can look at the W3C web server logs to get a feel for what sorts of user agents are retrieving ReSpec from the W3C servers?
  4. Would it be reasonable to provide some diagnostic information about the user agent when we make a request to specref (so that we can do analysis on usage)?  Maybe only the first time a specific document is requested (e.g., set a cookie)?


--
Shane McCarron
Projects Manager, Spec-Ops
Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Tobie Langel-4
On Wed, 11 May 2016, at 21:31, Shane McCarron wrote:
  1. Would it be reasonable to provide some diagnostic information about the user agent when we make a request to specref (so that we can do analysis on usage)?  Maybe only the first time a specific document is requested (e.g., set a cookie)?
 
I don't really want to get into the business of gathering user data (not to mention being compliant with EU cookie laws). I also don't think this would help us very much to identify non-W3C scenarios, as those don't necessarily rely on the Specref.
 
To answer your question more directly, I think you should cater to the community you want to grow and not try to be everything to everyone.
 
--tobie
Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Michiel Bijl
In reply to this post by Shane McCarron-6
At APG we only use to link to branches during calls, that’s pretty much it.

—Michiel

On 11 May 2016, at 21:31, Shane McCarron <[hidden email]> wrote:

As one of the ReSpec maintainers, I am often concerned that changes we make to the implementation will break stuff.  And given some recent events, I think that concern is merited.

One question that keeps coming up is "how is ReSpec used?"  Is it only used by document editors and the publication system, is it also used by the working groups and reviewers (in that they are looking at live documents), or is it used even more broadly?

We know that ReSpec is used by communities outside of the W3C, for example.

My basic concern can be characterized as "if we start using [insert new cool browser feature] in ReSpec, will our constituents still be able to use ReSpec?"  Or, to turn that around, "Are there people using ancient user agents actively accessing live documents written with ReSpec?"

So, a few questions for the group:
  1. Do you have a feel for how ReSpec is being used?
  2. Is there a policy about how far "back" we need to continue supporting user agents?
  3. Is there a way we can look at the W3C web server logs to get a feel for what sorts of user agents are retrieving ReSpec from the W3C servers?
  4. Would it be reasonable to provide some diagnostic information about the user agent when we make a request to specref (so that we can do analysis on usage)?  Maybe only the first time a specific document is requested (e.g., set a cookie)?


--
Shane McCarron
Projects Manager, Spec-Ops

Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Michiel Bijl
Which is needless to tell you Shane, as you are in it. Regardless, is your question whether it gets used outside of W3C?

—Michiel

On 02 Jun 2016, at 20:23, Michiel Bijl <[hidden email]> wrote:

At APG we only use to link to branches during calls, that’s pretty much it.

—Michiel

On 11 May 2016, at 21:31, Shane McCarron <[hidden email]> wrote:

As one of the ReSpec maintainers, I am often concerned that changes we make to the implementation will break stuff.  And given some recent events, I think that concern is merited.

One question that keeps coming up is "how is ReSpec used?"  Is it only used by document editors and the publication system, is it also used by the working groups and reviewers (in that they are looking at live documents), or is it used even more broadly?

We know that ReSpec is used by communities outside of the W3C, for example.

My basic concern can be characterized as "if we start using [insert new cool browser feature] in ReSpec, will our constituents still be able to use ReSpec?"  Or, to turn that around, "Are there people using ancient user agents actively accessing live documents written with ReSpec?"

So, a few questions for the group:
  1. Do you have a feel for how ReSpec is being used?
  2. Is there a policy about how far "back" we need to continue supporting user agents?
  3. Is there a way we can look at the W3C web server logs to get a feel for what sorts of user agents are retrieving ReSpec from the W3C servers?
  4. Would it be reasonable to provide some diagnostic information about the user agent when we make a request to specref (so that we can do analysis on usage)?  Maybe only the first time a specific document is requested (e.g., set a cookie)?


--
Shane McCarron
Projects Manager, Spec-Ops


Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Shane McCarron-6
APA / ARIA is an interesting case, in that we try to not expose the raw ReSpec to the public.  Since it is only "us" I am not super worried about it.  But there are some groups that make their ReSpec sources public and encourage use.  I was wondering how prevalent that is.

On Thu, Jun 2, 2016 at 1:25 PM, Michiel Bijl <[hidden email]> wrote:
Which is needless to tell you Shane, as you are in it. Regardless, is your question whether it gets used outside of W3C?

—Michiel

On 02 Jun 2016, at 20:23, Michiel Bijl <[hidden email]> wrote:

At APG we only use to link to branches during calls, that’s pretty much it.

—Michiel

On 11 May 2016, at 21:31, Shane McCarron <[hidden email]> wrote:

As one of the ReSpec maintainers, I am often concerned that changes we make to the implementation will break stuff.  And given some recent events, I think that concern is merited.

One question that keeps coming up is "how is ReSpec used?"  Is it only used by document editors and the publication system, is it also used by the working groups and reviewers (in that they are looking at live documents), or is it used even more broadly?

We know that ReSpec is used by communities outside of the W3C, for example.

My basic concern can be characterized as "if we start using [insert new cool browser feature] in ReSpec, will our constituents still be able to use ReSpec?"  Or, to turn that around, "Are there people using ancient user agents actively accessing live documents written with ReSpec?"

So, a few questions for the group:
  1. Do you have a feel for how ReSpec is being used?
  2. Is there a policy about how far "back" we need to continue supporting user agents?
  3. Is there a way we can look at the W3C web server logs to get a feel for what sorts of user agents are retrieving ReSpec from the W3C servers?
  4. Would it be reasonable to provide some diagnostic information about the user agent when we make a request to specref (so that we can do analysis on usage)?  Maybe only the first time a specific document is requested (e.g., set a cookie)?


--
Shane McCarron
Projects Manager, Spec-Ops





--
Shane McCarron
Projects Manager, Spec-Ops
Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Marcos Caceres-4
On June 3, 2016 at 5:13:52 AM, Shane McCarron ([hidden email]) wrote:
> APA / ARIA is an interesting case, in that we try to not expose the raw
> ReSpec to the public. Since it is only "us" I am not super worried about
> it. But there are some groups that make their ReSpec sources public and
> encourage use. I was wondering how prevalent that is.

Can you explain what "make their ReSpec sources public" means (or
point to some examples)? I'm not sure what that means exactly.

Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Shane McCarron-6
It means that the gh-pages branch is raw respec source, not static saved output of respec.  Examples?  Sure.  http://w3c.github.io/webpayments-ig/VCTF/use-cases/ for example.  Basically everyone who uses respec at w3c EXCEPT ARIA / APA.  As far as I know.

On Thu, Jun 2, 2016 at 8:15 PM, Marcos Caceres <[hidden email]> wrote:
On June 3, 2016 at 5:13:52 AM, Shane McCarron ([hidden email]) wrote:
> APA / ARIA is an interesting case, in that we try to not expose the raw
> ReSpec to the public. Since it is only "us" I am not super worried about
> it. But there are some groups that make their ReSpec sources public and
> encourage use. I was wondering how prevalent that is.

Can you explain what "make their ReSpec sources public" means (or
point to some examples)? I'm not sure what that means exactly.



--
Shane McCarron
Projects Manager, Spec-Ops
Reply | Threaded
Open this post in threaded view
|

RE: ReSpec and how it gets used

Markus Lanthaler-4
On Friday, June 3, 2016 3:19 PM, Shane McCarron wrote:
> It means that the gh-pages branch is raw respec source, not static
> saved output of respec.  Examples?  Sure.  http://w3c.github.io
> /webpayments-ig/VCTF/use-cases/ for example.  Basically everyone who
> uses respec at w3c EXCEPT ARIA / APA.  As far as I know.

We, the Hydra W3C Community Group also have dynamic Respec documents.
Recently I more often got reports that those documents don't render properly for some users. The last one I heard was that a fully patched IE11 can't render them.. I haven't verified that yet though.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler




Reply | Threaded
Open this post in threaded view
|

RE: ReSpec and how it gets used

Shane McCarron-6

Can you send a link to the document?  We can do some testing.

On Jun 5, 2016 7:15 AM, "Markus Lanthaler" <[hidden email]> wrote:
On Friday, June 3, 2016 3:19 PM, Shane McCarron wrote:
> It means that the gh-pages branch is raw respec source, not static
> saved output of respec.  Examples?  Sure.  http://w3c.github.io
> /webpayments-ig/VCTF/use-cases/ for example.  Basically everyone who
> uses respec at w3c EXCEPT ARIA / APA.  As far as I know.

We, the Hydra W3C Community Group also have dynamic Respec documents.
Recently I more often got reports that those documents don't render properly for some users. The last one I heard was that a fully patched IE11 can't render them.. I haven't verified that yet though.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler



Reply | Threaded
Open this post in threaded view
|

RE: ReSpec and how it gets used

Markus Lanthaler-4
On Sunday, June 5, 2016 4:11 PM, Shane McCarron wrote:
> Can you send a link to the document?  We can do some testing.

The main one can be found at http://www.hydra-cg.com/spec/latest/core/

Thanks



On Jun 5, 2016 7:15 AM, "Markus Lanthaler" <mailto:[hidden email]> wrote:
On Friday, June 3, 2016 3:19 PM, Shane McCarron wrote:
> It means that the gh-pages branch is raw respec source, not static
> saved output of respec.  Examples?  Sure.  http://w3c.github.io
> /webpayments-ig/VCTF/use-cases/ for example.  Basically everyone who
> uses respec at w3c EXCEPT ARIA / APA.  As far as I know.

We, the Hydra W3C Community Group also have dynamic Respec documents.
Recently I more often got reports that those documents don't render properly for some users. The last one I heard was that a fully patched IE11 can't render them.. I haven't verified that yet though.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler




Reply | Threaded
Open this post in threaded view
|

RE: ReSpec and how it gets used

Marcos Caceres-4
In reply to this post by Markus Lanthaler-4
On June 5, 2016 at 10:15:12 PM, Markus Lanthaler
([hidden email]) wrote:
> We, the Hydra W3C Community Group also have dynamic Respec documents. Recently I more
> often got reports that those documents don't render properly for some users. The last
> one I heard was that a fully patched IE11 can't render them.. I haven't verified that yet
> though.

IE11 is not supported by ReSpec's generation mode, unfortunately (that
browser is over 2 years old now, and has been superseded by Edge).
Either kindly ask your users to switch to Edge or use a more modern
browser ... alternatively, please publish the ReSpec output instead,
which should work on any browser going back to IE6.

Reply | Threaded
Open this post in threaded view
|

RE: ReSpec and how it gets used

Travis Leithead-2
It's also possible your users were running into an issue recently patched for Edge (that also affected IE11): https://github.com/w3c/respec/pull/799

-----Original Message-----
From: Marcos Caceres [mailto:[hidden email]]
Sent: Monday, June 6, 2016 7:40 PM
To: Shane McCarron <[hidden email]>; Markus Lanthaler <[hidden email]>; spec-prod <[hidden email]>
Cc: Michiel Bijl <[hidden email]>
Subject: RE: ReSpec and how it gets used

On June 5, 2016 at 10:15:12 PM, Markus Lanthaler
([hidden email]) wrote:
> We, the Hydra W3C Community Group also have dynamic Respec documents.
> Recently I more often got reports that those documents don't render
> properly for some users. The last one I heard was that a fully patched
> IE11 can't render them.. I haven't verified that yet though.

IE11 is not supported by ReSpec's generation mode, unfortunately (that browser is over 2 years old now, and has been superseded by Edge).
Either kindly ask your users to switch to Edge or use a more modern browser ... alternatively, please publish the ReSpec output instead, which should work on any browser going back to IE6.

Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Tab Atkins Jr.
In reply to this post by Marcos Caceres-4
On Mon, Jun 6, 2016 at 7:40 PM, Marcos Caceres <[hidden email]> wrote:

> On June 5, 2016 at 10:15:12 PM, Markus Lanthaler
> ([hidden email]) wrote:
>> We, the Hydra W3C Community Group also have dynamic Respec documents. Recently I more
>> often got reports that those documents don't render properly for some users. The last
>> one I heard was that a fully patched IE11 can't render them.. I haven't verified that yet
>> though.
>
> IE11 is not supported by ReSpec's generation mode, unfortunately (that
> browser is over 2 years old now, and has been superseded by Edge).
> Either kindly ask your users to switch to Edge or use a more modern
> browser ... alternatively, please publish the ReSpec output instead,
> which should work on any browser going back to IE6.

As a reader of ReSpec'd specs, I'd highly appreciate it if more people
published the generated output instead of the sources.  It avoids the
flash-of-unprocessed-content and subsequent anchor-jumping, and it
works better in the tooling infrastructure.

~TJ

Reply | Threaded
Open this post in threaded view
|

RE: ReSpec and how it gets used

Markus Lanthaler-4
On 7 Jun 2016 at 17:40, Tab Atkins Jr. wrote:
> On Mon, Jun 6, 2016 at 7:40 PM, Marcos Caceres <[hidden email]> wrote:
>> On June 5, 2016 at 10:15:12 PM, Markus Lanthaler
>> ([hidden email]) wrote:
>>> We, the Hydra W3C Community Group also have dynamic Respec documents.
>>> Recently I more often got reports that those documents don't render
>>> properly for some users. The last one I heard was that a fully patched
>>> IE11 can't render them.. I haven't verified that yet though.
>>
>> IE11 is not supported by ReSpec's generation mode, unfortunately (that

Bummer


>> browser is over 2 years old now, and has been superseded by Edge).
>> Either kindly ask your users to switch to Edge

Well, that might be tricky for lots of users as it also requires an OS update.


>> or use a more modern browser ... alternatively, please publish the
>> ReSpec output instead, which should work on any browser going
>> back to IE6.

I'm not going to ask to start supporting IE11 again but what browser support do you aim for? Only the absolute latest version? IE11 still seems to have a considerable market share...


> As a reader of ReSpec'd specs, I'd highly appreciate it if more people
> published the generated output instead of the sources.  It avoids the
> flash-of-unprocessed-content and subsequent anchor-jumping, and it
> works better in the tooling infrastructure.

The thing I like most about ReSpec is that it doesn't need any "compilation" step. It's not perfect but for most use cases it works well enough.


--
Markus Lanthaler
@markuslanthaler


Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Shane McCarron-6
Comments in line

On Tue, Jun 7, 2016 at 2:11 PM, Markus Lanthaler <[hidden email]> wrote:

>> browser is over 2 years old now, and has been superseded by Edge).
>> Either kindly ask your users to switch to Edge

Well, that might be tricky for lots of users as it also requires an OS update.

Agreed.  Moreover, this is not an option for many users (see below).
 
>> or use a more modern browser ... alternatively, please publish the
>> ReSpec output instead, which should work on any browser going
>> back to IE6.

I'm not going to ask to start supporting IE11 again but what browser support do you aim for? Only the absolute latest version? IE11 still seems to have a considerable market share...


We have no clear guidelines on this  My inclination is to never break faith with backward compatibility unless maintaining it forces a reduction in primary function.  I suspect we have made a mistake removing whatever polyfill enabled IE11 support.   And while I agree with some other commenters that publishing static versions is a better end user experience anyway, the reality is that many working groups are developing specs using ReSpec, and those groups don't want to take the time to generate static versions - in particular for their "Editor's Draft"s.  So to the extent that we want people to be able to readily review specs as they are in development, we need to take this into consideration.

Note that I am not talking about the people writing the specs.  I assume they are working with relatively modern user agents.  They are typically geeks like us.  But their constituents are often less tech-savvy.  The Web Payments community, for example, has A LOT of bankers in it.  Conservative organizations tend to lock down software and only upgrade rarely, and then after acceptance testing.  But they are nonetheless members of the W3C, and should be able to review and comment on our specs.



> As a reader of ReSpec'd specs, I'd highly appreciate it if more people
> published the generated output instead of the sources.  It avoids the
> flash-of-unprocessed-content and subsequent anchor-jumping, and it
> works better in the tooling infrastructure.

The thing I like most about ReSpec is that it doesn't need any "compilation" step. It's not perfect but for most use cases it works well enough.


Yes.  It is what drew many of us to ReSpec.  The recent instability has made it a much less desirable platform.  My groups have spent a lot of time trying to resolve ReSpec introduced problems or learning new requirements as features change.   Worse yet, various changes have broken the tool chain that enabled the automated generation of "TR" versions of specs or otherwise made it impossible to publish without hand-editing.  

As a maintainer of ReSpec, I am appalled.  As a user, I am frustrated.  As an advocate, I am finding it a hard product to recommend.  

Perhaps the solution is to make all the (named) versions available so that document developers can choose the one that works well for them and their users?  Or identify a stable version and call that official, then leave the "development" bleeding-edge that people can use or not.  Do a migration to stable periodically after substantial testing. I don't know.  But something needs to change.  Right now I see the best case as people forking ReSpec so they have something they can rely upon.  I see the worst case as them abandoning the platform. Both of these would be a failure.


--
Shane McCarron
Projects Manager, Spec-Ops
Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Marcos Caceres-4
In reply to this post by Tab Atkins Jr.
On June 8, 2016 at 1:40:32 AM, Tab Atkins Jr. ([hidden email]) wrote:
> As a reader of ReSpec'd specs, I'd highly appreciate it if more people
> published the generated output instead of the sources. It avoids the
> flash-of-unprocessed-content and subsequent anchor-jumping, and it
> works better in the tooling infrastructure.

Agree. Working towards that... part of this making Echidna easier to
use/integrate into projects (and to put an end to Editor's drafts).

I'm trying different things to kill the FOUC and stop the jumping
around. But will mean some breaking changes, so need to get some
groups to stop using ReSpec's crappy "events" model.

Reply | Threaded
Open this post in threaded view
|

RE: ReSpec and how it gets used

Marcos Caceres-4
In reply to this post by Markus Lanthaler-4
On June 8, 2016 at 5:11:57 AM, Markus Lanthaler
([hidden email]) wrote:
> I'm not going to ask to start supporting IE11 again but what browser support do you aim
> for? Only the absolute latest version? IE11 still seems to have a considerable market
> share...

Not amongst the tiny group of people who produce specs.

Anyone publishing source documents without going through the spec
generator is doing harm to their readers. It's really inexcusable
given that we have had Echidna for over a year and we worked so hard
to get the auto-publish process in place at the W3C.

Even if you don't want to use Echidna, you can run
`./tools/respec2html.js` locally when you check in your spec to have
it generated for you.

If people have any problems with generation, I'm happy to help them get set up!

As one of ReSpec's maintainers, and for the benefit of those that rely
on our specs, I would really like to see less ReSpec buttons (and
FOUC!) and more specs on /TR/.

Let's work towards making that super easy.

Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Marcos Caceres-4
In reply to this post by Shane McCarron-6
On June 8, 2016 at 5:37:19 AM, Shane McCarron ([hidden email]) wrote:

> Comments in line
>
> On Tue, Jun 7, 2016 at 2:11 PM, Markus Lanthaler
> wrote:
>
> >
> > >> browser is over 2 years old now, and has been superseded by Edge).
> > >> Either kindly ask your users to switch to Edge
> >
> > Well, that might be tricky for lots of users as it also requires an OS
> > update.
> >
>
> Agreed. Moreover, this is not an option for many users (see below).

But this is an option for everyone who writes specs. I've never met
anyone at the w3c who is in this situation (or can't use another
browser).

> > >> or use a more modern browser ... alternatively, please publish the
> > >> ReSpec output instead, which should work on any browser going
> > >> back to IE6.
> >
> > I'm not going to ask to start supporting IE11 again but what browser
> > support do you aim for? Only the absolute latest version? IE11 still seems
> > to have a considerable market share...
> >
>
>
> We have no clear guidelines on this My inclination is to never break faith
> with backward compatibility unless maintaining it forces a reduction in
> primary function. I suspect we have made a mistake removing whatever
> polyfill enabled IE11 support.

There was nothing removed. Just stuff got added. IE11 is not
maintained, so it breaks because it's been left behind by the Web.

> And while I agree with some other
> commenters that publishing static versions is a better end user experience
> anyway, the reality is that many working groups are developing specs using
> ReSpec, and those groups don't want to take the time to generate static
> versions - in particular for their "Editor's Draft"s. So to the extent
> that we want people to be able to readily review specs as they are in
> development, we need to take this into consideration.

Agree. This is a long process - but we need to work as a community to
get there.

> Note that I am not talking about the people writing the specs. I assume
> they are working with relatively modern user agents. They are typically
> geeks like us. But their constituents are often less tech-savvy. The Web
> Payments community, for example, has A LOT of bankers in it. Conservative
> organizations tend to lock down software and only upgrade rarely, and then
> after acceptance testing. But they are nonetheless members of the W3C, and
> should be able to review and comment on our specs.

Sure, and again the best way to serve them is to give them generated
snapshots (even of EDs).

> >
> > > As a reader of ReSpec'd specs, I'd highly appreciate it if more people
> > > published the generated output instead of the sources. It avoids the
> > > flash-of-unprocessed-content and subsequent anchor-jumping, and it
> > > works better in the tooling infrastructure.
> >
> > The thing I like most about ReSpec is that it doesn't need any
> > "compilation" step. It's not perfect but for most use cases it works well
> > enough.
> >
> >
> Yes. It is what drew many of us to ReSpec. The recent instability has
> made it a much less desirable platform. My groups have spent a lot of time
> trying to resolve ReSpec introduced problems or learning new requirements
> as features change. Worse yet, various changes have broken the tool chain
> that enabled the automated generation of "TR" versions of specs or
> otherwise made it impossible to publish without hand-editing.

This is no different to Bikeshed or Anolis or any other piece of
software. Software breaks, things change. We patch stuff quickly and
move on.
¯\_(ツ)_/¯

> As a maintainer of ReSpec, I am appalled. As a user, I am frustrated. As
> an advocate, I am finding it a hard product to recommend.

It's open source, you are free to leave, fork, use BikeShed, whatever
¯\_(ツ)_/¯.

I like the improvements I've made - and sure, there was a little pain
for a tiny number of people for maybe a couple of hours, but whatever.
At least it's actually getting maintained and updated now - and it's
vastly better.

A year ago, it was "stable" in the sense that it was rotting away
because no one was spending any time improving it after Robin left.
That's not stability: that's just bit rot.

> Perhaps the solution is to make all the (named) versions available so that
> document developers can choose the one that works well for them and their
> users? Or identify a stable version and call that official, then leave the
> "development" bleeding-edge that people can use or not.

That's what we do today. We develop in branches, which go to
"develop", which then get released into "gh-pages".

>  Do a migration to
> stable periodically after substantial testing. I don't know. But something
> needs to change. Right now I see the best case as people forking ReSpec so
> they have something they can rely upon. I see the worst case as them
> abandoning the platform. Both of these would be a failure.

I think you are totally over dramatizing things. Little bugs are no
big deal. Most people haven't noticed that we've done like 40+
releases in the last year.

Reply | Threaded
Open this post in threaded view
|

RE: ReSpec and how it gets used

Matt King
I don't know if this is the right thread for this comment ... if not, feel free to let me know.

I am an editor and I rely on the JAWS screen reader. Because Firefox has to be updating is accessibility tree as respect runs, it takes a really long time to run. It is rare that I am able to start reading a branch in rawgit in under a minute. The ARIA spec takes up to 2 minutes before I can read it. Then, sometimes, like today, things are very broken. Today, none of the roles, states, or property sections have headings or permalinks. I don't know if that is due to a new respec bug or a failure of respect to run completely, or a defect in my spec text. Today, I know it is not a defect in my text because I haven't changed it since it last worked.

I am wondering if there is a better way for respect to work. Is there a way to make all the respec changes without doing it on the live DOM and then replace the entire DOM or something like that. Content hidden with display none is left out of the AX tree, so maybe the whole DOM could be hidden while the processing is occurring ... maybe not great for everyone, but at least you would all have an experience that is more like mine <smile>.

Matt King

-----Original Message-----
From: Marcos Caceres [mailto:[hidden email]]
Sent: Wednesday, June 8, 2016 2:47 AM
To: Shane McCarron <[hidden email]>
Cc: Michiel Bijl <[hidden email]>; spec-prod <[hidden email]>
Subject: Re: ReSpec and how it gets used

On June 8, 2016 at 5:37:19 AM, Shane McCarron ([hidden email]) wrote:

> Comments in line
>
> On Tue, Jun 7, 2016 at 2:11 PM, Markus Lanthaler
> wrote:
>
> >
> > >> browser is over 2 years old now, and has been superseded by Edge).
> > >> Either kindly ask your users to switch to Edge
> >
> > Well, that might be tricky for lots of users as it also requires an
> > OS update.
> >
>
> Agreed. Moreover, this is not an option for many users (see below).

But this is an option for everyone who writes specs. I've never met anyone at the w3c who is in this situation (or can't use another browser).

> > >> or use a more modern browser ... alternatively, please publish
> > >> the ReSpec output instead, which should work on any browser going
> > >> back to IE6.
> >
> > I'm not going to ask to start supporting IE11 again but what browser
> > support do you aim for? Only the absolute latest version? IE11 still
> > seems to have a considerable market share...
> >
>
>
> We have no clear guidelines on this My inclination is to never break
> faith with backward compatibility unless maintaining it forces a
> reduction in primary function. I suspect we have made a mistake
> removing whatever polyfill enabled IE11 support.

There was nothing removed. Just stuff got added. IE11 is not maintained, so it breaks because it's been left behind by the Web.

> And while I agree with some other
> commenters that publishing static versions is a better end user
> experience anyway, the reality is that many working groups are
> developing specs using ReSpec, and those groups don't want to take the
> time to generate static versions - in particular for their "Editor's
> Draft"s. So to the extent that we want people to be able to readily
> review specs as they are in development, we need to take this into consideration.

Agree. This is a long process - but we need to work as a community to get there.

> Note that I am not talking about the people writing the specs. I
> assume they are working with relatively modern user agents. They are
> typically geeks like us. But their constituents are often less
> tech-savvy. The Web Payments community, for example, has A LOT of
> bankers in it. Conservative organizations tend to lock down software
> and only upgrade rarely, and then after acceptance testing. But they
> are nonetheless members of the W3C, and should be able to review and comment on our specs.

Sure, and again the best way to serve them is to give them generated snapshots (even of EDs).

> >
> > > As a reader of ReSpec'd specs, I'd highly appreciate it if more
> > > people published the generated output instead of the sources. It
> > > avoids the flash-of-unprocessed-content and subsequent
> > > anchor-jumping, and it works better in the tooling infrastructure.
> >
> > The thing I like most about ReSpec is that it doesn't need any
> > "compilation" step. It's not perfect but for most use cases it works
> > well enough.
> >
> >
> Yes. It is what drew many of us to ReSpec. The recent instability has
> made it a much less desirable platform. My groups have spent a lot of
> time trying to resolve ReSpec introduced problems or learning new
> requirements as features change. Worse yet, various changes have
> broken the tool chain that enabled the automated generation of "TR"
> versions of specs or otherwise made it impossible to publish without hand-editing.

This is no different to Bikeshed or Anolis or any other piece of software. Software breaks, things change. We patch stuff quickly and move on.
¯\_(ツ)_/¯

> As a maintainer of ReSpec, I am appalled. As a user, I am frustrated.
> As an advocate, I am finding it a hard product to recommend.

It's open source, you are free to leave, fork, use BikeShed, whatever
¯\_(ツ)_/¯.

I like the improvements I've made - and sure, there was a little pain for a tiny number of people for maybe a couple of hours, but whatever.
At least it's actually getting maintained and updated now - and it's vastly better.

A year ago, it was "stable" in the sense that it was rotting away because no one was spending any time improving it after Robin left.
That's not stability: that's just bit rot.

> Perhaps the solution is to make all the (named) versions available so
> that document developers can choose the one that works well for them
> and their users? Or identify a stable version and call that official,
> then leave the "development" bleeding-edge that people can use or not.

That's what we do today. We develop in branches, which go to "develop", which then get released into "gh-pages".

>  Do a migration to
> stable periodically after substantial testing. I don't know. But
> something needs to change. Right now I see the best case as people
> forking ReSpec so they have something they can rely upon. I see the
> worst case as them abandoning the platform. Both of these would be a failure.

I think you are totally over dramatizing things. Little bugs are no big deal. Most people haven't noticed that we've done like 40+ releases in the last year.



Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and how it gets used

Shane McCarron-6
I was aware that you were having issues Matt.  I was not aware they were quite this dire.  Can you send us / me the URI to your rawgit tree so I can figure out what the respec issue is?  As far as I know the ARIA trees were fixed to work with the current ReSpec a couple of weeks ago.

As to your suggestions....  the approach I had wanted to take was to set aria-busy to true on the body element until respec and any extensions were complete.  ReSpec added a Promise that should facilitate this.  Do you think this approach would work?

On Wed, Jun 8, 2016 at 5:47 PM, Matt King <[hidden email]> wrote:
I don't know if this is the right thread for this comment ... if not, feel free to let me know.

I am an editor and I rely on the JAWS screen reader. Because Firefox has to be updating is accessibility tree as respect runs, it takes a really long time to run. It is rare that I am able to start reading a branch in rawgit in under a minute. The ARIA spec takes up to 2 minutes before I can read it. Then, sometimes, like today, things are very broken. Today, none of the roles, states, or property sections have headings or permalinks. I don't know if that is due to a new respec bug or a failure of respect to run completely, or a defect in my spec text. Today, I know it is not a defect in my text because I haven't changed it since it last worked.

I am wondering if there is a better way for respect to work. Is there a way to make all the respec changes without doing it on the live DOM and then replace the entire DOM or something like that. Content hidden with display none is left out of the AX tree, so maybe the whole DOM could be hidden while the processing is occurring ... maybe not great for everyone, but at least you would all have an experience that is more like mine <smile>.

Matt King

-----Original Message-----
From: Marcos Caceres [mailto:[hidden email]]
Sent: Wednesday, June 8, 2016 2:47 AM
To: Shane McCarron <[hidden email]>
Cc: Michiel Bijl <[hidden email]>; spec-prod <[hidden email]>
Subject: Re: ReSpec and how it gets used

On June 8, 2016 at 5:37:19 AM, Shane McCarron ([hidden email]) wrote:
> Comments in line
>
> On Tue, Jun 7, 2016 at 2:11 PM, Markus Lanthaler
> wrote:
>
> >
> > >> browser is over 2 years old now, and has been superseded by Edge).
> > >> Either kindly ask your users to switch to Edge
> >
> > Well, that might be tricky for lots of users as it also requires an
> > OS update.
> >
>
> Agreed. Moreover, this is not an option for many users (see below).

But this is an option for everyone who writes specs. I've never met anyone at the w3c who is in this situation (or can't use another browser).

> > >> or use a more modern browser ... alternatively, please publish
> > >> the ReSpec output instead, which should work on any browser going
> > >> back to IE6.
> >
> > I'm not going to ask to start supporting IE11 again but what browser
> > support do you aim for? Only the absolute latest version? IE11 still
> > seems to have a considerable market share...
> >
>
>
> We have no clear guidelines on this My inclination is to never break
> faith with backward compatibility unless maintaining it forces a
> reduction in primary function. I suspect we have made a mistake
> removing whatever polyfill enabled IE11 support.

There was nothing removed. Just stuff got added. IE11 is not maintained, so it breaks because it's been left behind by the Web.

> And while I agree with some other
> commenters that publishing static versions is a better end user
> experience anyway, the reality is that many working groups are
> developing specs using ReSpec, and those groups don't want to take the
> time to generate static versions - in particular for their "Editor's
> Draft"s. So to the extent that we want people to be able to readily
> review specs as they are in development, we need to take this into consideration.

Agree. This is a long process - but we need to work as a community to get there.

> Note that I am not talking about the people writing the specs. I
> assume they are working with relatively modern user agents. They are
> typically geeks like us. But their constituents are often less
> tech-savvy. The Web Payments community, for example, has A LOT of
> bankers in it. Conservative organizations tend to lock down software
> and only upgrade rarely, and then after acceptance testing. But they
> are nonetheless members of the W3C, and should be able to review and comment on our specs.

Sure, and again the best way to serve them is to give them generated snapshots (even of EDs).

> >
> > > As a reader of ReSpec'd specs, I'd highly appreciate it if more
> > > people published the generated output instead of the sources. It
> > > avoids the flash-of-unprocessed-content and subsequent
> > > anchor-jumping, and it works better in the tooling infrastructure.
> >
> > The thing I like most about ReSpec is that it doesn't need any
> > "compilation" step. It's not perfect but for most use cases it works
> > well enough.
> >
> >
> Yes. It is what drew many of us to ReSpec. The recent instability has
> made it a much less desirable platform. My groups have spent a lot of
> time trying to resolve ReSpec introduced problems or learning new
> requirements as features change. Worse yet, various changes have
> broken the tool chain that enabled the automated generation of "TR"
> versions of specs or otherwise made it impossible to publish without hand-editing.

This is no different to Bikeshed or Anolis or any other piece of software. Software breaks, things change. We patch stuff quickly and move on.
¯\_(ツ)_/¯

> As a maintainer of ReSpec, I am appalled. As a user, I am frustrated.
> As an advocate, I am finding it a hard product to recommend.

It's open source, you are free to leave, fork, use BikeShed, whatever
¯\_(ツ)_/¯.

I like the improvements I've made - and sure, there was a little pain for a tiny number of people for maybe a couple of hours, but whatever.
At least it's actually getting maintained and updated now - and it's vastly better.

A year ago, it was "stable" in the sense that it was rotting away because no one was spending any time improving it after Robin left.
That's not stability: that's just bit rot.

> Perhaps the solution is to make all the (named) versions available so
> that document developers can choose the one that works well for them
> and their users? Or identify a stable version and call that official,
> then leave the "development" bleeding-edge that people can use or not.

That's what we do today. We develop in branches, which go to "develop", which then get released into "gh-pages".

>  Do a migration to
> stable periodically after substantial testing. I don't know. But
> something needs to change. Right now I see the best case as people
> forking ReSpec so they have something they can rely upon. I see the
> worst case as them abandoning the platform. Both of these would be a failure.

I think you are totally over dramatizing things. Little bugs are no big deal. Most people haven't noticed that we've done like 40+ releases in the last year.





--
Shane McCarron
Projects Manager, Spec-Ops
12