[Meta] Project Goals

[swyxio]

Hi! We've accumulated a longish list of todos' right about now, so right now we kind of need to converge rather than diverge.

I'm particularly interested in scoping down of a small set of recipes that we can get published soon. That gives us a small win that can help us get contributors and momentum for the next round.

This involves defining project goals and principles. Here's my thoughts - lets take a week for people to give input and then I'll help execute on whatever we agree on.

External Inspiration

• https://vuejs.org/v2/cookbook/index.html
• https://github.com/markerikson/react-redux-links
• anything else?

High level Objectives

• Fast Self Service support for frequently asked questions
• Help Svelte adopters make high quality experiences thru best practices
• Teach idiomatic/creative use of Svelte features to solve problems
• Highlight notable community projects beyond the main docs

Principles we follow

• Consider SEO in Naming
  • Essential for self service goal
  • Build link equity to encourage people to contribute, and link to their own domains and blogpost
  • This is why we don't call this a "Cookbook" - just easier to use plural "Recipes"
• Beginner friendly but Showing Best Practice
  • It is ok to duplicate main docs but not too much
  • Start simple, progress up to advanced
• "How" First, "Why" Later
  • Working examples to copy & paste for initial success.
  • Link to REPL if possible.
  • Explain why/principles for subsequent success

V1 candidates

Let's "go to market" with 5 recipes:

• Using Fetch to Consume APIs with Svelte
• Form Validation with Svelte
• Using SASS and TypeScript with Svelte Preprocessors
• Routing with Svelte
• authentication patterns https://antony.github.io/svelte-meetup-talk-oct-2019/#6

Open Questions for discussion

• What do we NOT include?
• How do we differ from just being a very wordy Svelte Tutorial?
• "Maintainers" for each Recipe? ownership => quality

[antony]

"Maintainers" for each Recipe? ownership => quality

I think this is a good idea, and solves one of the problems the core team were concerned about, which is, who upholds quality / takes the burden of maintenance with these third party recipes.

How do we differ from just being a very wordy Svelte Tutorial?

I think having a focus on the clear, concise wording that the official tutorials have, and emulating the styling there will help.

https://antony.github.io/svelte-meetup-talk-oct-2019/#2

These were the 5 most wanted topics from the discord - I'm not sure much has changed in terms of the questions asked, so maybe the 5th candidate should be configuration (spoiler: it's complex due to bundling and lack of process.env.*).

[kevmodrome]

Here's some more external inspiration: https://hexdocs.pm/phoenix/overview.html

Scope seems good. Maybe adding a bit about how to do authentication using things like auth0 as the last recipe?

I think most tutorials these days are really just recipes. It's fine if they're in the 5-10 minute reading length.

[kevmodrome]

Async Library Loading is probably a better candidate than auth, seeing the list that @antony linked to.

[tanhauhau]

from the "go to market", I see roughly 2 theme here

• How to build an app

  • how to use fetch and consume api
  • how to validate a form
  • how to lazy load component / image

• How to set up

  • set up router?
  • set up typescript, sass
  • set up babel?

so we can probably think and expand from this 2 directions.

what do you think?

[swyxio]

@tanhauhau yeah. if you see the main readme i have reorged the top level architecture to

• Build Setup Recipes
• Svelte Language Fundamentals
• Svelte Component Recipes
• Svelte Store Recipes
• Svelte Action Recipes
• Svelte Transition Recipes
• Svelte App-Level Design Patterns
• Svelte Performance Tips
• Testing and Debugging Svelte
• Publishing Svelte Components/Deploying Svelte Apps
• Special Usecase Walkthroughs

so we would be doing 2 out of this list, with room to grow in future..

i broke it out like this because "how to build an app" is super broad

arguably "Svelte Language Fundamentals" should just be docs but @pngwn felt it should be here 🤷‍♂

[pngwn]

We don’t have anywhere for it right now, and I doubt anything drastic is going to happen anytime soon in that regard, due to lack of time.

I popped them here because at least they exist somewhere. Worth mentioning that the more general stuff was under the working title of “guides” rather than “cookbook”.

Feel free to get rid of them, but they won’t be going anywhere else for the time being as far as I can see.

[swyxio]

mm interesting. we dont HAVE to call these things recipes - do people think we should pivot to Guides?

lol, this is why we do MVPs, to find out things like this haah

[swyxio]

just found the gatsby recipes page - https://www.gatsbyjs.org/docs/recipes/

[dmgolembiowski]

@sw-yx, I was wondering if there's any room to discuss some more fundamental topics like Events and the DOM?


When the Svelte documentation starts to talk about concepts like "bubbling phase" and "cancelable events" -- I'm just thinking to myself "Um.. so yeah... those are words", and lose focus on what the documentation is talking about, because it'll go right over my smol brain.

But all the while I'm wondering what an example was trying to teach me. My hunch is that in order to use examples like these, it's imperative to first have some prior knowledge. Moreover, I don't think it's possible to even use Svelte to the fullest extent unless you're already a subject matter expert in TypeScript, vanilla JS, and probably React (but that's a big assumption). On the other hand, I don't think it's this repository's role to be a big brother/sister to the collective Svelte community, but I do think it's sensible to adopt the Rust community's utopia-like warmth toward its newcomers.


As Fletcher Nichol put it in his recent talk on Habitat, there are clever people who get discouraged when using their clever ideas don't get accepted by the compiler; and they get discouraged when exceptional people come along and make everything look effortless: but in reality, these people are just that -- exceptional.
Did anyone else feel this way when they first came to Svelte?

[swyxio]

whoa, sorry i dont know why it was locked and limited, that was accidental, sorry. @dmgolembiowski i would say that is of course a nice to have, but Svelte isn't there yet. in terms of Documentation levels - we are level 2, moving to level 3. there's a LOT to cover and we dont have that many volunteers. need to support and grow our existing community. being beginner friendly is important, but duplicating other resources out there is a nice-to-have imo. people can always ask questions about bubbling and cancelation in the chat and github and stackoverflow.

[dmgolembiowski]

@sw-yx Good point 😅 ; and don't worry -- I just figured that my behavior was a bit too overzealous and warranted locking the thread from outside contributors. Thanks for following up!

[swyxio]

not at all, it was totally unintentional, possibly buttdialed it from my phone