[work item proposal] Solid Application Requirements

[michielbdejong]

[EDITED X2]

This is a CG work item to produce a new specification which Solid apps should adhere to, with the goal of binding together:

• existing client-client specs such as Solid Chat and Solid WebID Profile
• existing data convention registries such as ShapeRepo, PDS Interop Conventions and the one that SolidLab Flanders are working one
• existing app launchers
• existing access control mechanisms such as SAI, WAC, ACP, Distri and remoteStorage scopes

This new spec document will detail the necessary and sufficient requirements an app should adhere to in order for it to be compatible with Solid, hence the name "Solid Application Requirements".

We will have a weekly work meeting, open to all CG participants and under the Solid CG CoCC, every Friday 16:00 CET in https://meet.jit.si/solid-ux-dx-improvements.

[VirginiaBalseiro]

Thanks for bringing this up. I agree that focus on improving user and developer experience for Solid is important.

The general understanding is that there are major blocks of initiatives and work in the Solid Project. Specification-centric work is carried out under W3C with the Solid CG and potentially the Solid WG. There are also other significant initiatives that are Solid Project wide. For example, the Solid Practitioners Group is one of those ("bottom-up") undertakings. We also briefly entertained the possibility of a Business Group. And, as you know, the Solid Team stuff.

I think what you're raising highlights a need of the Solid Project as a whole. It might be beneficial to consider Practitioners' Group as a potential venue for this work, or perhaps there is a need to create another group focusing specifically on developing code / libraries.

@jeff-zucker and I have discussed having more coordination and collaboration between PG and CG. This closer coordination will be highly beneficial to ensure that input and feedback coming from PG makes its way into the specs.

If there is interest in producing documents alongside the code, it would be helpful to clarify the type of document you have in mind. Some documentation efforts might align with the scope of the CG, such as Primers, Best Practices and Guidelines, and Use Cases and Requirements; while others could be better suited for different kinds of groups within the Solid Project. For instance, documents aimed at onboarding developers could be developed in the Getting Started Group.

[jeff-zucker]

I think it is an excellent idea to support the development of code and libraries. I don't think the CG is the place for that to happen. The CG really needs to concentrate on the important work of getting the specs written and into a standards track.

ongoing work to become more central and more visible in the project

I think this is also a valuable goal. It seems to me to fit within the Solid Team - that is the place where the CG, the Practitioners, the GettingStarted Group, your group, and others can come togehter in a way that we each support the others.

When I first suggest Practitioners, I suggested it to be within the CG and was told pretty firmly that outreach and support were not in scope of CG but were in scope of the team. Since your project involves both outreach to developers to let them know about the tools and support for those developing the tools, that seems to fit within the team. That doesn't mean the team supervises those projects, it means the projects hasve an easy path to let all of the outlets know and track practice and for collaborations between CG-Practitioners-Onboarding-UX to take place.

[michielbdejong]

When I first suggest Practitioners, I suggested it to be within the CG and was told pretty firmly that outreach and support were not in scope of CG but were in scope of the team.

Right! Those were different times though:

• there was no proposed WG yet
• we still had panels
• we had a full-time spec editor chairing the CG

We have a chance to reconsider now, how we can best manage our project with minimal overhead and maximum progression on its goals.

Looking at the Solid Project with fresh eyes, if the 1.0 spec, its test suite, the panels we used to have, Solid Practitioners, Solid OS, the website, Pivot, SolidCommunity.net, MeIsData.io, Solid Data Modules and Solid Compound all don't fall under the CG then I would like to see a list of activities that do happen under the CG, and rough number of FTE working on them.

What comes to mind off the top of my head:

• SAI (~1 FTE?)
• special topic meetings (<.2 FTE?)
• weekly CG call (<.2 FTE?)
• Solid Lite (<1 FTE?)
• anything I forgot?

What we don't want is a CG with more chairs and overhead than actual activity, and then all the interesting Solid Project activities (like Practitioners but also the others I listed) being told they're out of scope. The Solid project has always been about docs + code + specs + tests + practice, not just specs, so we shouldn't define the CG too narrowly.

I'll see if I can find some W3C guidelines about what CGs in general are meant to work on, and what they're meant to leave to their fringes.

[michielbdejong]

Right, looking at https://www.w3.org/community/about/#cg and https://www.w3.org/community/about/faq/ it does seem that building actual implementations is quite explicitly out of scope for W3C CGs, the goal should really be to write specs and test suites.

But there is nothing there to say that the writing process should not include experimentation, and that also largely how I see the work item I'm proposing here. It just needs a bit of rewording then.

So not all Solid Data Modules activity can be in scope unless we rebrand the code we write there as just reference / test suite code (which is not such a big step actually).

For Practitioners and Solid OS it might indeed be preferable to say they're not CG activities. I would like to find a way though to make sure that what we spec in the CG matches what is needed in Practitioners and in Solid OS, in terms of implementation feedback and input about stumbling blocks experienced by developers and practitioners. Apart from Jeff's reports about practitioners to the team, I think that's still missing a bit. But let's make that a separate discussion.

[michielbdejong]

https://github.com/solid/specification/issues/615#issue-2078622083 updated following your reactions - @VirginiaBalseiro and @jeff-zucker please re-review

[michielbdejong]

My main motivation is that currently if we point two developers to https://solidproject.org/TR/ and ask them both to write a Solid app, they will probably write apps that are not interoperable with each other, which sort of defeats the purpose of using Solid in the first place. The proposed UX/DX guidelines spec will hopefully help to fix that.

[VirginiaBalseiro]

TL;DR:

I've reviewed this discussion again, as I see it, your proposal cuts close to the "Getting Started with Solid" work but should be considered to extend to incorporate the things you'd like to see.

---

What we don't want is a CG with more chairs and overhead than actual activity,

There are numerous open challenges (issues, call for implementations or commitments) on record within the scope of the CG. The chairs can focus on encouraging participants to advance that work.

and then all the interesting Solid Project activities (like Practitioners but also the others I listed) being told they're out of scope.

Interesting activities can and should happen in and out of the CG, under the Solid Project's umbrella and in different groups and task forces. There is no reason why CG should contain every interesting activity going on in the project, and these activities can also be taken into account in the CG in different forms, such as implementer's feedback, implementation reports. CG participants are also actively engaged with implementers and their projects' conformance with Solid specifications, along with support in chats and forums. "Being told" is CG consensus as reflected by our charter, which was thoroughly discussed, reviewed, and approved.

The Solid project has always been about docs + code + specs + tests + practice, not just specs, so we shouldn't define the CG too narrowly.

The W3C Solid CG charter:

As per W3C structures for groups and W3C Process, the Community Group will maintain its focus on incubating technical reports, prototyping software, and testing implementations within the Scope of the charter, with the aim of advancing mature works to the W3C Recommendation track in a Working Group.

Furthermore, the CG has a wide range of topics in its scope, and it is anything but "narrow": https://www.w3.org/community/solid/charter/#scope

Solid Team has a list of activities that already align with your proposal: https://github.com/solid/team/pull/39 . Namely:

• Create a Better Onboarding Experience for Developers
• Create a Better Onboarding Experience for Users

My main motivation is that currently if we point two developers to https://solidproject.org/TR/ and ask them both to write a Solid app, they will probably write apps that are not interoperable with each other, which sort of defeats the purpose of using Solid in the first place. The proposed UX/DX guidelines spec will hopefully help to fix that.

Those are separate (and important) points. If developers are writing apps that are not interoperable, then it reinforces the point that the proposed specifications for interoperability are not yet adequate. That work is already within the scope, and so I can only encourage us to continue that work further.

As I mentioned earlier, drafting Primers can further help developers as well contributors to specifications. It would help to know exactly which kind of UX/DX document you have in mind as the output of the work you're proposing.

As I see it, your proposal cuts close to the "Getting Started with Solid" work but should be considered to extend to incorporate the things you'd like to see.

Right! Those were different times though:

Different times? The CG charter was accepted in 2023-09. How much has changed since then?

• there was no proposed WG yet

The WG charter was publicized in 2023-09. And the CG worked on it throughout 2023 in the months leading up to it.

• we still had panels

They were not particularly active and there were plenty of discussions to move away from them throughout the year.

• we had a full-time spec editor chairing the CG

Meaning what exactly? How is this relevant to the scope? Scope is a CG decision aligned with W3C expectations, and was discussed thoroughly by CG participants.

[michielbdejong]

Those are separate (and important) points. If developers are writing apps that are not interoperable, then it reinforces the point that the proposed specifications for interoperability are not yet adequate. That work is already within the scope, and so I can only encourage us to continue that work further.

Thank you! So the question is, should we distribute that work over the existing work items such as Solid Application Interoperability and Solid Chat or is there a gap to be filled between them?

[VirginiaBalseiro]

Right, some of the UX/DX work you mention could be developed as part of those specifications. My understanding is that this kind of work is or should be taken into account as part of incubation, and generally part of implementation feedback. Other guidelines on these topics could be developed as an extension to Getting Started, and Primers, for example.

[michielbdejong]

Thanks also for discussion in Matrix DM. You're right, a CG work item should not have "guidelines" in its title, and a lot of the work from the Solid Compound milestones would fall under Solid Practitioners and not Solid CG. But there is still quite a bit of work to do in normatively binding together the specs on the client side, so restricting the scope of this work item to just normative spec work, and changing the title to 'Solid Application Requirements'.

[jeff-zucker]

Right! Those were different times though:

• there was no proposed WG yet
• we still had panels
• we had a full-time spec editor chairing the CG

You are mistaken. I proposed this just a month or so ago during the CG charter discussion at which time none of those things was true.

Message ID: @.***>

[michielbdejong]

OK I see. Basically, I'm proposing that 1) "getting Solid working" should be in-scope for the CG. I don't see much point in having a CG if it's just editing specs as loose sand without being guided by that goal. 2) Currently, let's face it, Solid isn't working yet. We don't have interop between https://solidproject.org/apps, we have many different access control mechanism, many different notification channels, we don't have fine-grained access control working, and we don't have app launchers where an end-user can just try out some demo apps and see them working. 3) We (including but not limited to the Solid Data Modules team and the Solid Compound team) are working on fixing this. 4) Given the situation of 2), the work of 3) should be in-scope for 1). Hence this work item proposal to represent it.

Let's discuss in the next CG call! If we can't agree on having this work in-scope for Solid CG then it can still be in-scope for Solid Project / Solid Team of course, but I consider that a plan B.

In the meantime, we will be working on this and having weekly work meetings at 15:00 UTC (16:00 Amsterdam time) each Friday in https://meet.jit.si/solid-ux-dx-improvements

[michielbdejong]

After some more thought and useful conversation with @VirginiaBalseiro and others, I'll first propose a Solid Team task force about this work, to give it a place, and then if we're ready to be writing specs we can always still morph it into a CG work item at that time.

[michielbdejong]

See https://matrix.to/#/!ogHmAuzhszmxlGQrVp:gitter.im/$iQ-NfYJW7zbReu4glJymRm2puVp8KuwVgWBfXm19EBE?via=gitter.im&via=matrix.org&via=attendees.fosdem.org and https://github.com/solid/team/pull/54

[csarven]

@michielbdejong , @VirginiaBalseiro , you beat me to responding in this thread :) but I've been thinking and PR'd a simple guide about Workspace Selection inspired by this issue and discussion elsewhere (e.g., CG charter with Jeff): https://github.com/w3c-cg/solid/pull/16 . I think that can help us quickly address common scenarios and keep some perspective/focus.

Just want to also acknowledge that what's brought up in this issue is important and useful. IMO, the work goes beyond the CG, and would even include the WG, and in various ways Practitioners, and as Michiel (just said as I'm writing this) DX/UX work in general in the community.