search

solid / solidproject.org

Website for solidproject.org
https://solidproject.org
MIT License
148 stars 101 forks source link

Reorg part1 redirect tutorials #793

Closed kay-kim closed 1 year ago

kay-kim commented 1 year ago

Per earlier May 24 meeting discussion -- An initial PR for the start of the cleanup work:

timea-solid commented 1 year ago

I tried to push this along a bit. Regarding naming of the tutorial: I do not care if it says Inrupt or not.

oolivo commented 1 year ago

A couple thoughts.

  1. This content is currently live with a broken and unmaintained tutorial. Can we get this fixed ASAP. Either remove the whole tutorials section and all links to it or replace it with a working tutorial (even if a temporary band-aid). If we would like to reconsider our approach to tutorials, then I propose that be taken up in a separate PR or issue to figure out our long term tutorial strategy, as that was not the goal of this PR. We are currently holding up updates to what is currently broken content. It's been broken for quite some time. This needs to get fixed immediately, it's embarrassing for the whole project.

  2. "all resources referring to that URL should also include other tutorials from the Solid community." - Are there any other tutorials from the Solid community that are actively maintained? If so, great, then please provide a list of them and we can talk about a strategy for curating and maintaining the list at the next Solid Team Meeting. But someone from the team will have to put in the effort to ensure that all linked tutorials are actively maintained and comply with the spec. Otherwise we'll just be linking to a bunch of stale or broken tutorials a year from now and be in the same boat. If these tutorials don't exist, or no one on the team is willing to own curation, then this is all moot.

  3. I'm OK for the Inrupt tutorial to be linked to from SolidProject.org and live in the Inrupt docs(option 3), but again, if it's the only tutorial in the list of tutorials that's maintained and curated, then we're probably overthinking/overanalyzing it. It'll look worse to have a list of tutorials with only one entry.

  4. This is a simple content update to broken and stale materials as far as I can tell, why has this been in review for a month? If we plan to be better about maintaining SolidProject.org long term, then we have to find a way to make these reviews more efficient, focused, and goal oriented. The contents is currently incorrect and out of date and every developer who visits solidproject.org right now will have a bad experience with a tutorial that does not work. Let's work towards addressing the immediate issue please. The rest can be taken up once we have things back to a stable state.

csarven commented 1 year ago

The PR is open because 1) there has been only two reviews (one of which is only concerned about content clarity), 2) a key consideration is raised as part of a review which hasn't been resolved yet - literally has to do with clarifying / agreeing on what the resource in question is supposed to identify because everything else follows from that. The options suggested to move forward are not particularly complicated. What's stalled is that the proper decision to make doesn't match the contents of the proposed changes in the PR.

There is another way to move things super fast: push code right into the main branch without reviews.

oolivo commented 1 year ago

  1. To be clear. The fact that it's over taking a month to get a "simple" change in is a statement fact, not an opinion and not directed at any one person. If you took it as a statement directed specifically at you that was not the intention. It is an observation that we as a team need to have more urgency in resolving issues and be more efficient in how we work. If we need more reviews let's get more reviews. If we need to have an out of band meeting to reach a decision, let's schedule a meeting. I'll repeat. The "Getting started with Solid" tutorial is broken. It has been broken for quite some time. This is every potential developer community members first experience with Solid. The top priority should be getting a working tutorial out on the site ASAP. All other long term changes and discussion about the tutorial strategy, format, and layout should be had once the existing defects are addressed. We can change the resource name now or later. I do not agree that "everything else follows from that". If the contents that are currently live are broken, then debating the resource name is a secondary concern if a decision can't be reached quickly. It's had the same resource name it has for years now, it can wait until another PR to sort out. Let's get a working tutorial up ASAP.

  2. I agree the options presented for moving forward are not particularly complicated. But choosing the correct option and reaching consensus on that will take time as people have differing opinions. And during that time, the live tutorial continues to be broken. I actually believe none of the options proposed are viable long term. So we either need to have a conversation where a decision can be made, recorded, and implemented ASAP or we fix the tutorial contents (as was this PR's intention) and discuss naming and other things at a later time in a separate PR. If the issue you have is with the redirect, then we can copy and paste the tutorials contents into solidproject.org directly and then it will literally be the status quo we have had for years now, but it will get out of date and we'll be right back here in 6 months. So for now, a redirect (or link) to an actively maintained tutorial seems the best option. We can link it, but since there is only one tutorial to link to, it doesn't look great from a web design/management standpoint. If we had multiple tutorials to reference then I might support the linking approach. But we would still have the curation problem. And given how short staffed we are on the Solid team, curating tutorials is going to fall by the wayside. @kay-kim do we have a Java tutorial ready to go that we can add if we go the linking route so we at least have 2 things we can point to?

Can we aim to get this resolved this week?

csarven commented 1 year ago

I'm asking for a clarification on what the resource is about because the changes related to the resource (as identified by the URI) in the PR do not appear to be adequate. Answering that simple inquiry will also help (others) better review and improve the solution.

What does the URI https://solidproject.org/developers/tutorials/first-app identify?

This shouldn't be a debate. The URI owner(s) should be able to give a clear answer.

If anything, use it as a simple exercise to document what's intended, and can still get back to it later.

Random patching of content as things eventually caught fire and the countless redirects on the website now has been a maintenance nightmare. There needs to be URI Templates and proper URI allocations, if there is to be any sense of a strategy for the website going forward. #solidteamagenda

Merge as is or not. Get more reviews or not. Go with yet another solution if that seems preferable. Heck, I'll even remove my change request if off chance anyone feels that's posing a blocker or something (LOL).

kay-kim commented 1 year ago

W.r.t.

@kay-kim do we have a Java tutorial ready to go that we can add if we go the linking route so we at least have 2 things we can point to?

Yes. If we want to, we can link to https://docs.inrupt.com/developer-tools/java/client-libraries/getting-started/

kay-kim commented 1 year ago

Just a heads up ... I'm going to manually rebase and push again to this branch -- this shouldn't affect the actual changes in this branch.