Proposal: Simplify the Solid organization structure

[aschrijver]

Keep it small and simple. Solid forgot the KISS principle and now it is an interwoven mess of procedures, teams, panels, repositories, and more. Here are some ideas that appeal to me personally to simplify:

• Have two github organizations to separate different concerns:

  • Solid: Everything that has to do with specification development, nothing more.
  • SolidProject: Everything that has to do with implementation of the specification.

• Solid github organization has:

  • specification repository.
  • panel-discussion repository.
  • solidproject-website repository.
  • (probably some more, I didn’t go through the list)

• Solid Project website focuses on clearly explaining the spec, and what it brings to implementers.

  • Change the site look&feel from a product website to a documentation website.
  • Create accessible documentation for a broad (dev) audience, add diagrams, animations, etc.
  • Does the site need a separate staging repo? I think not.
  • Does the site need a process on top of the PR process? I think not.
  • Define a github team for Editors, have projects with a kanban board for issue tracking
  • Define templates for issues and PR’s, assign clear labels for issues.
  • Kill the MIT website, or have it redirect. It is yet another confusing entrypoint to Solid initiative.

• Panel Discussion repository squashes all panel repo’s into one single location.

  • Have one top-level README to drill-down into the panel structure.
  • Have issue labels indicating to which panel the issue belongs.
  • Have teams per panel, and a project + kanban board per panel, Assign issues to panel members.
  • Update a Changelog upon closing an issue, part of Definition of Done. What was the outcome?
  • Have stalebot auto-close issues untouched for 6 months. They are probably unimportant.
  • Use new Discussions feature of github, if you don’t want to use forum (add pointer instead).
  • Remove elaborate, overly formal Process repository. Small explainer + some bullet points suffice.
  • Could even remove issue tracker from Specification repo: all goes through panel discussion.

• SolidProject repo contains all the various code projects.

  • Should only contain ‘official’ repo’s (probably already does).
  • Have clear naming conventions, libs, tools, sdks, reference impls, examples, pocs, etc.
  • Archive every repo that is old an out-of-date.
  • Mention all official repo’s on Solid Project website in a single page and highlight their purpose.

• Solid community forum can become more interesting for the community + core members.

  • An easy way to improve and liven up the forum is to assign active members as moderator.
  • If moderators become inactive, after a while, they lose their spot if they don’t pick up.

• Solid initiative now consists of only 4 parts forming an onion model from outside in:

  1. Solid Project website: First point of contact, top-level entry, onboarding, facilitate early adopters.
  2. Solid Community forum: Free-form discussion, ideation, sharing insights, giving feedback.
  3. Solid Panel discussion: Formalising feedback for standardization, elaborate technical concepts.
  4. Solid Gitter channel: Active member day-to-day chatter, hop in for quick question / feedback

Thoughts?

(PS. Also posted to Improving the effectiveness of Panels issue in github Process repository.)

[aschrijver]

@MitziLaszlo, @justin if any of this makes sense, could you bring it to the attention of other core members?

[justin]

@aschrijver appreciate the concrete breakdown of suggestions

@aschrijver

Have two github organizations to separate different concerns:

• Solid : Everything that has to do with specification development, nothing more.
• SolidProject : Everything that has to do with implementation of the specification.

I don’t disagree with this approach though i’m not sure that a “project” suffix is enough to substantially delineate one grouping from the other. Archiving and moving repositories around can sometimes lead to consternation and complaints on its own, so before we consider that it’d probably be better to clean up the places that led them to github (i.e. solidproject.org, solid.mit.edu), so they’re getting linked to the appropriate places, with the appropriate context, to start with.

@aschrijver

Solid Project website focuses on clearly explaining the spec, and what it brings to implementers.

• Change the site look&feel from a product website to a documentation website.
• Create accessible documentation for a broad (dev) audience, add diagrams, animations, etc.

Completely agree with these first points.

@aschrijver

• Does the site need a separate staging repo? I think not.
• Does the site need a process on top of the PR process? I think not.

• Whether or not it should have a staging repo is really up to those doing the most edits.
• Editorial review via PR is the important element for me, but if those producing the most content feel an extension to the process helps them do well that should be fine.

@aschrijver

• Define a github team for Editors, have projects with a kanban board for issue tracking
• Define templates for issues PR’s, assign clear labels for issues.

• We already have a github team for editors
• If you have some suggestions for issues/pr templates or labels, that would be helpful.

@aschrijver

Kill the MIT website, or have it redirect. It is yet another confusing entrypoint to Solid initiative.

It’s probably a worthy time to look at whether any requirement to maintain an MIT base couldn’t be satisfied with a dedicated page on solidproject.org.

@aschrijver

Panel Discussion repository squashes all panel repo’s into one single location.

I think it’s up to the panels to determine how they want to operate. That said, I’m happy to raise a combined repository with various panels and see if anyone is receptive.

@aschrijver

An easy way to improve and liven up the forum is to assign active members as moderator.

Can you expand on how the added moderation would translate to an improved forum?

–

I think the topic name could probably be adjusted to better illustrate that this is a proposal with actionable suggestions.

Thanks for putting time and thought into this @aschrijver

[aschrijver]

Solid project website

@justin

• We already have a github team for editors
• If you have some suggestions for issues/pr templates or labels, that would be helpful.

Ah, I see (the link in editorial section is broken). The Creators project board.

I gave graphql.org before as a good example site. They have a master and source branch instead of a separate staging repo. Every page has an ‘Edit this page’ link that immediately starts the PR process. You see that they have 335 contributors.

Note that imho it is an illusion to think that any volunteer will write significant parts of the website. For GraphQL the vast majority of pages are written by Lee Byron, the maintainer. Then there are some larger contributions, but most of them are corrections, grammar improvements, clarification and code snippet improvements. But still worthwhile.

You may consider to contract a technical writer to set up and maintain the website. Given the importance of good documentation this money will not be wasted I think.

Wrt templates it depends a bit how the site is set up, and how low you want the barrier to contribute to be. That’s why I suggested removing the process on top of PR’ing. (These procedures may exist, but keep them in the background, out of sight of the contributor).

First of all I suggest somewhere to have a bullet-point list on writing style guidelines (“keep your sentences short”, “use simple understandable language”, “briefly explain new concepts in ways a newbie would understand”, “add a link to more elaborate explanation for the interested reader”, etc.).

Also a good list of terminology that is mandatory to use should be provided. Consistent terminology without synonyms and other confusing ways of describing is key.

Then in the issue / PR templates there can be something of a Definition of Done checklist:

• Did you re-read and edited your sentences several times?
• Did you check spelling and grammar correctness?
• Did you use terminology from our glossary where appropriate?
• Does your text adhere to the writing style guidelines?

You could have issue template for Documentation Request.

• Describe what you want to see included in the documentation
• Explain why it is important to include these aspects. Why is it important to Solid?
• If you have them provide pointers to relevant related information resources.

You could have an issue template for a Terminology Change Request.

• Describe the change you want to make to official terminology
• Why is it important to make this change? What value does it add to the Solid project?

Solid panels

Problem with current spread out panels is that they are not only distant to anyone that is not a very active Solid member, but that they constitute silo’s to the panel teams themselves. Do you check all the panel repo’s regularly to see if issues also apply to certain extent to your panel’s subject?

All in all the total number of issues in all panels is not that large. There are many OSS projects that effectively manage way larger amounts of issues. Click on ‘panel topic’ and ‘priority’ labels and immediately have the list of issue to add to board ToDo backlog.

For people like me, and other interested in Solid, it would be great to just have to follow a single repo to have insight in all that is going on in standards elaboration.

Solid forum

@justin

Can you expand on how the added moderation would translate to an improved forum?

First of all this forum is not as active as it should be. That is because Solid has neglected community-building. That is a pity, as you are missing out on a lot of activity that can help Solid move forward more rapidly. It’s why I posted Proposal: Build a stronger Solid community presence.

The Discourse software is crammed full of features to help make forum content more valuable. But they take a lot of time to be applied appropriately. Time that you or other forum staff may not have (many staff members are not active on the forum, btw).

Pinning important threads (globally and per category), changing categories, adding new categories if needed, tagging topics, splitting tangential posts from a discussion, creating wiki posts, marking answers as solution. There are many of these things that forum regulars may be willing to pick up, and alleviates you of the burden to do it. Facilitating community projects, create teams/groups is then another step further that can be supported.

Finally it is also a way to strengthen the community, if they take part in community forum moderation.

[MitziLaszlo]

@aschrijver thank you for the thoughtful input, especially the specificity of the proposals. @justin thanks for chipping in and bouncing ideas around here too.

Glad it seems like you’ve already found the best entry points for overview information about the standardisation process, the website management, and an overview of panels.

Further suggestions for simplification of the process and consolidation of information flow are always welcome so I’ll try and link your proposals to related relevant conversations and share some ideas on how to move forward together. (For example, a few places where conversations like this are best to continue are GitHub Repo Naming, Adding Panel Chairs, and Improving effectiveness of panels.)

[justin]

@aschrijver

if any of this makes sense, could you bring it to the attention of other core members?

Just wanted to say that we’re actively working on this. This was great input and it’s not being overlooked.