Help Me Understand Documentation Holes #167
Comments
ryansolid
added
help wanted
|
I think having a formal API generated from the codebase would be very helpful; sometimes it's hard to find which methods are available, what are they called or what types of values are accepted (I'm thinking about all the possible way to call setState). Given it's a typescript codebase, https://typedoc.org could be helpful, even if it's not the most flexible generator (it looks something like this on a project of mine: https://framp.me/frappe/docs) My background is mainly React and derivates (from Classes to Fn/Hooks) + a fair amount of elm + very little vue.
I probably would have described the system starting from reactivity and introducing the simpler primitive and then building up to state. |
|
I know there's an open issue about SSR & SSG, but a more detailed documentation about it and how to set it up would be really nice. I think that's going to spark a lot of interest, especially if you manage to get it close to Marko/Svelte rendering. |
|
@framp this is great stuff. The state naming is an interesting thing in the post Hooks world. See I started calling that beforehand because I was trying to emulate React Class Components state object. But now people are used to
Yes I need to document create solid better.. It is just a fork of Create React App. I just pointed at CRA docs because that all applies but it's worth talking about that. For instance adding module.css as the extension I think does CSS modules out of the box(https://create-react-app.dev/docs/adding-a-css-modules-stylesheet/). The problem is there is so much in CRA that I don't know how it works. Of course I should just make that a lot clearer. Thank you so much for this feedback. @amoutonbrady .... hah.. you got me. This is purposefully cryptic right now since I'm making breaking changes even in patch versions. I shouldn't be but I don't want to bump the minor version to infinity while I work on this. I know how to get Marko/Svelte performance but it comes at real cost given the scenarios I want to support. I almost have to start over and build up again to get there. Basically they render a static string with no reactivity on the server this makes advanced patterns very limited. But there are different sorts of solutions once you accept that. I'm still profiling the cost of reactivity. So far seems I can get Vue like performance, but have to make a call whether that is good enough. |
|
I can't really talk about what the experience of someone with no experience in other frontend frameworks would be, since I'm not that person, but as someone who has mostly only worked with React as well, coming to Solid when I see things that are named "Effect" or "State", I would really want to know either exactly how they differ to React effects and state, or if they are substantially different, it would be nice if they were named something else entirely. I think the problem with the current explanation of Solid State in the README is that it isn't 100% clear exactly how effects or state work in Solid. For example, React hooks execute every single render, or if you add state variables into the dependency array, only when those state variables get updated. In Solid's README if you read the provided example code one might be able to deduce that the effect only executes if state variables used inside are set through their setters, but it would be good if this was stated explicitly in the explanation. Also, it still leaves a few questions unanswered, like "so does the effect ever execute if state variables inside are not set?", and "if one uses a specific path inside the state object, does the effect only execute if that path is updated? Or just whenever the setter is called?". Whichever is the case, a more explicit explanation would be nice. You also don't explain:
The two linked introductory articles are a bit better, but explain by showing some amount of the implementation, which can be insightful, especially in this case where the underlying implementation isn't hugely complicated, but can also be confusing to some people. Generally speaking as well, while talking about implementation detail can be fine if it is explained clearly why they make things work they way they do, it introduces one more thing that a new user needs to understand, and is only useful if it helps them understand how to use the library, or helps them understand why the library is good/superior. I also understand if the introduction on State is merely meant to motivate, not explain, but in that case I would expect a more thorough explanation on both State and Effect somewhere else in the official documentation (and not an article written on another site). And also, if the goal was to motivate, personally speaking, I don't see from the provided examples how the library is all that different to React, and if I was a beginner it wouldn't really occur to me why Reactivity is even that important in the first place. It's only through digging through other parts of documentation and the two articles that any of it clicks into place. The Reactivity.md document starts by talking about Signals, but I hesitate to actually read about them, because 1. I'm not sure whether it's actually necessary to understand them, and 2. the actual explanation for what signals actually are seems to mostly be a very heavy two paragraph section titled "Accessors Reactive Scope" which should really have more code examples to demonstrate what you mean by things like "reactive scope" and "can be nested as many levels as desired". If signals are just implementation detail then I don't really want to read about them. |
|
@louisch Thank you this cuts to the heart of it. I've had difficulty explaining the reactive update model without going into implementation. Any wordy explanation sounds like vague generalizations or like I'm selling magic. This always detracts from having a simple message. I do see a couple commonalities here:
|
|
@ryansolid I think you should include this example shared state between multiple components also how to use createEffect without running into issues |
|
@junaid1460 did you remove another example? I actually liked that one. Since it showed something that I took for granted. Computations re-track dependencies on every execution. If you ever hit branching logic that doesn't depend on a reactive stat the other branch will never evaluate and the branch itself won't since it isn't being tracked. I think the execution cycle of reactivity tracking could be better explained. As for the CodeSandbox example has a lot going on so I'm unclear what precisely you are trying to demonstrate. Generally I recommend following React-like patterns even if it is unnecessary. I find that code organization easier to understand the basics like It is possible to hoist out signals and state, but you don't want to do so with effects and memos since they will never be released. For that reason I strongly suggest following the Context pattern. I have examples about how that works and docs. But maybe I need a more of.. writing your first app etc.. Or like after a writing your first Component, a next steps. I'm thinking this mostly boils down to having good tutorials. The examples are ok, the docs definitely have holes, but as much of it is they go too deep in areas a beginner doesn't care to as of yet. I need the documentation to be complete but there should be a path for people who don't care for those details. I introduced state early to let people coming from React try easy stuff almost as a drop in. |
|
Yeah, kinda changed it. with making two components almost similar except for one line. I was trying to explain how tracking works. May be you could include a simple example in a best practice doc Also there's some other pattern like passing JSX element directly in props might cause duplication like for example function Test({array, index}:{array: any[], index: number }) {
return array[index]
}
function Root({index}: {index) {
// Avoid this
<Test array={[<MyBigComponent></MyBigComponent>, <i></i>]} index={index} />
}
function Test2({array, index}:{array: any[], index: number }) {
return array[index]()
}
function Root({index}: {index) {
// do this
<Test2 array={[() => <MyBigComponent></MyBigComponent>,() => <i></i>]} index={index} />
}This looks very minor issue, but this might cause mem leak while using external libraries like monaco or Pickr, also too many subscriptions to state if element uses state. I think a good dev tool for chrome can notice these issues and notify. May be I'll try to build one. |
|
Is the confusion that all dynamic props are lazily evaluated? And: <MyBigComponent />
// roughly equals
MyBigComponent()Because I don't see an issue in the first case if that is what you are going for. Can you explain why don't do this? I also notice you use a lot of destructuring which shouldn't be a problem here but could lead to missing reactive triggering. I'm thinking that something even more fundamental is missing in the docs and following that assumption we've gotten out here somewhere. Maybe there is a bug here that I'm missing as I expect the first scenario to be fine. Maybe my heuristic for dynamic wrapping is incorrect in these component cases? I feel like I'm missing part of what is trying be achieved here. Using |
|
I have migrated a project from react to solid, I noticed this with a tab component, during change, updates were triggered in two createEffects, out of which one is visible and another was just invoked by this |
|
Haven't tried solid yet, but read a few articles by @ryansolid & documentation pages in this repo. Solid looks like a very promising project and I really want to see it gaining more traction among developers. With that, I'd strongly recommend the project to have its official website with documentation before/with going v1.0. If you're already planning on that, please disregard the rest of this comment. 😅 As silly as it sounds, presentation matters. A lot. A nice, clean website to go with the documentation will attract new users and help to retain current users. This is especially true for those who are not as knowledgeable/interested in the underlying technologies but still curious about what the next big thing might be or simply looking for some great off-the-shelf tools to build applications with. A link to the project website also looks much better than to its GitHub repo when spreading the word. Unfortunately, https://github.com/ryansolid/solid just doesn't give off an impression that this is more than an experiment. Nothing too crazy--something as simple as https://recoiljs.org/ should suffice in my opinion. You already have all the materials. Best of luck to you! |
|
@bobaekang I agree completely. It is already in the works. I hope to get it in place soon. It is probably the biggest outstanding piece for 1.0. I wouldn't mind stabilizing on SSR a bit more and a bit of cleanup around Resource APIs for Suspense. I think starter templates could be improved too. I appreciate the feedback. |
@ryansolid could you please drop a link to repo here. I'd like to take that up. |
|
Right now it's a private repo. I will likely change when I have something to show. |
|
Can you elaborate on Does |
|
Just started looking at Solid (having found it via interest in Svelte). I'm most familiar these days with React (and Redux), but have used a bunch of approaches/tools over the years (including good ol' VanillaJS). Solid looks very interesting, especially as I've hit some performance bumps recently with React in a side project. I know I can work around them, but I keep having this feeling that browers and JS are incredibly powerful these days and we are actually getting in our own way with a lot of our 'solutions'. So Solid's focus on being fast resonates a lot! Regarding docs, some general points that would help folks like me jump in are:
Right now there is a ton of information that I've read through about Solid that's got me excited about it. But I also notice that I haven't yet tried playing with it because I dread having to make a bunch of decisions (even which 'starter' to use). Reducing those decisions by providing a strong opinion would help a lot here. I looked over the realworld and hackernews source. I think it would be amazing to document the decisions made (and accompanying rationale) when implementing those - could be the basis of the tutorial? Are they recommended patterns for Solid usage? By the way, the general explanation of why (along with the what and how) in the current docs/articles is very useful and something often overlooked in docs. Distilling these down into a summary of the tradeoffs made could be helpful to folks evaluating potential fit for their projects. Lastly, a tie-in with an existing service can be a boon to adoption and visibility. I saw #100 and think that getting an article on their learning section could be a good idea. They are also a good example of real-world articles that get you into their product by showing how it works with other common products (like Auth0). |
|
Really like the idea of having a tutorial/tour page of Solid's features. |
|
@martinpengellyphillips Yeah I did try to streamline at least getting started. The challenge is everyone has their own opinion. I have Create Solid App. And truthfully the fact that I wouldn't use my own starter probably says something. In general, I've found the process on tooling has generally been I suggest something and everyone points out how they have a different use case. This is a problem with the JS ecosystem in general. There is no one size fits all here. For larger projects people have more patience for bloat. I find most early adopters would rather start pretty minimalist so something like Create Solid is way overkill. But it also isn't there for them. I pictured most people would just start there as documented. I tried to write an article for how to build TodoMVC but I feel it fell short. The real challenge is answering "why" without getting into very specific details of the reactive system. From my perspective most libraries gloss over this a bit. They just go, this is how you do blank which I think is probably sensible from an intro perspective if why makes the explanation 4 times longer. Personally I think the single best way to try SolidJS without any commitment is modifying one of the over a dozen examples from CodeSandbox I link off the readme. That's how I learn. That's the poor man's version of tutorials. Which really just brings us back to the tutorial/guides which keep coming back in these comments. I'd love to be able to do something like that. But it starts with getting a REPL setup. Something nice that shows code running, as well as compilation output. That is pretty much the requirement to make those tutorials effective. I've had Solid compile in the browser before using Babel Standalone but this needs to be much better. With that I think the rest of this comes. I'm not sure if there are existing editor tools that can be used? I know Svelte built theirs from scratch. I could make an issue around creating a REPL. It's just one of many things that will take some doing. As much as I'd like to do stuff like this to promote the library. I've resigned myself to prioritize things that only I can do at this point and things that others could help with like say Routing, creating a Website, or creating a REPL I'm going to leave out there for now. If anyone wants to help would be super appreciative. Otherwise I will get there eventually. |
|
@ryansolid I hear ya!
I personally don't think you need a REPL tutorial (it's a nice to have). What I was thinking more about was some clearer sense of "Ryan's sitting down to start a new project with Solid - what do they do?". And I think that, as the creator, you totally get to give your opinion without worrying about satisfying everyone elses 😄 And maybe you don't use starter templates and just spin things up from scratch. If so, I'd say that in the intro/tutorial because it helps establish the culture ('lean and mean', 'back to basics', 'understand your tools', ...) and it also avoids folks spinning the wheels too much on 'am I doing this as intended?'
I totally clocked that and it was a stumbling block for me getting started because I wanted to know why doesn't Ryan use this? Can I do what they do instead?.
I think that's a good way to try bits of Solid, but for me it's not a hook to use Solid. I need to build something with it and see how the pieces fit together. And that means I need low friction on getting started on my own project. As an aside, CodeSandbox is typically slow so not a great compliment to a project that focuses so much on performance 😉. Also, some of the examples (e.g. form) seem slightly broken and there is a lot to go through up front. BUT, to stay true to my earlier point, if you think lots of examples via sandboxes is the way to go, then just stating that clearly will help folks get in the groove. In the meantime, I'll take a punt at converting one of my existing apps to Solid and let you know how it goes. |
|
I'm not sure if I've missed this, but one topic that may be worth covering is how to generally approach the integration of 3rd party vanillaJS libraries with Solid (e.g. libraries for animations, drag-and-drop, etc.). This is a topic that has been in the back of my mind while thinking about (and very much wanting) to use solid for an upcoming personal project. I don't know if I've overlooked or just failed to understand something, but there could be other dumdums like me that are also unclear as to what to consider and how to approach trying to use existing vanillaJS libraries with Solid. |
|
That's fair. I think I assume too much React knowledge and don't provide any guides for this as it is a bit outside of what the library does. In one sense it's really simple, which is why it gets missed I think since: // this is an HTMLDivElement
const div = <div />In that it is pretty easy to do Vanilla JS since you just get a reference to the element and do what you would with it. You can also get refs via the ref bindings https://github.com/ryansolid/solid/blob/master/documentation/rendering.md#refs. If you need to cleanup when your component is destroyed you can add an Albeit I don't have great examples. This thread might be of interest: #39 I'd be interested in more concrete examples as a source for guides. |
|
As kind of the culmination of the long chain of questions I had in #215, I think this line: in the Reactivity docs could use a bit more elaboration. Reactivity in Effect and Memo are very clear, I've been basing my understanding of reactivity off of S, so those read to me just as S computations... But it's a lot more opaque when it comes to JSX, I think (Which is an issue I think I also have with Surplus). I originally interpreted this as meaning of "an expression in [the] JSX" as "a JSX expression" as in "All JSX is compiled to a createEffect call", which lead to the assumption that anything inside the body of a Component function would therefore be reactive, but from the conversation we had and the article you linked, I understand that's not the case. I'm assuming now that "an expression in JSX" is what the curly brace interpolation thing is called, and I guess I just never picked up on that. So, does this mean that any function that's ultimately invoked within JSX bracket whatevers is reactive? Does this apply universally, like in props and such? I think it would be useful for people who are prone to making way too many assumptions, such as myself, to explicitly lay out where the boundaries of reactivity are. EDIT: I think I might just be parroting what louisch said above. Also, when you say <Component someProp={getSignal()}/>Is not reactive, unless I were to use |
|
@Myrdden Yeah it's all good. It just means they can be better. I made a lot of changes thanks to @louisch comments. But you bring up such an obvious thing yet not obvious to me since I am in it all the time. Those curly brace things are called JSX Expressions in the spec and the AST parsed. I actually named the underly DOM Expressions after this concept but it is in no way obvious since in JSX from a JavaScript perspective everything is an expression. To answer your first question yes. Component execution bodies themselves are untracked, but every expression which can be reactive inside a JSX Expression is reactive. The compiler uses syntax analysis to determine this. Things that call functions or access members (like array or object property access) are treated like they are reactive. Function declarations, literal values, and simple identifiers that can never be tracked are not (it's a little bit more complicated than that but that's the message). Second question. With components the compiler instead of wrapping each prop in Still I've struggled to explain this. Lazy evaluation is necessary so that access happens inside a reactive context as desired. But I understand it isn't clear what that means since I sort of hide it behind property access. |
|
Neat, that totally cleared it up for me. My takeaway is basically that the assumption can be made that anything inside of Effect, Memo, or a JSX Expression is reactive, but I think that did a good job explaining why. One more question, how exactly does destructuring work? Is it just "never use it with reactive things"? I understand that Actually, while we're at it, it might be useful to have a list of potential pitfalls documented somewhere... |
|
Honestly I think this is the by far the biggest one. It's all variations on this topic of reactive context and reactive property access and tracking. All reactive libraries fundamentally work the same but since I don't do this at a Component scope it causes a lot of confusion. Unfortunately it is the thing that makes this approach interesting from performance standpoint. Why it is able to do the 1:1 updates that no other library even Reactive ones like Svelte can do. It's much easier to just say never destructure. But the truth is for something to be reactively tracked we need to call a function. We can hide that function behind a getter or a proxy but we need to call a function while the reactive context is executing. So nothing is wrong with destructring as long as you are in the right place. Destructuring is accessing properties on an object and assigning them to a value. A value can not be reactive. So it matters where you access that property, so a destructure tracks like any other reactive access. But if you do it at the top of your file no one is listening. I looked at Vue 3 docs for suggestions of how to explain this as they have the same problem in their setup function. But they just point to a helper that sort of destructures into a bunch of refs(signals). But it's verbose and expensive. I guess I could write simple function wrappers with explicit keys but it stops looking like destructuring. It becomes sort of self-defeating when the goal is to keep things terse. I could do it with a proxy maybe and keep the syntax tight. It wouldn't work in a rest parameter. Like: const {someProp} = toSignals(props);
// now someProp is a function and reactive when called.
someProp()The request has come up a couple times now. Any thoughts on something like that? A bit more ergonomic perhaps than We do have some other helpers like |
|
Personally I'm happy with "never destructure reactive props or else they'll break". I usually tend to use use |
|
Hello, another question... Maybe this goes in it's own ticket? Not sure. I recall you saying somewhere, I don't remember where, that const Component = () => <p>hello</p>;
const App = () => <div><Component/></div>;
// versus
const App = () => <div>{Component()}</div>;
// or even something like
const App = () => wrapDiv(Component());will these all function exactly the same? Or is there some other logic to EDIT: Forgot that I, as a programmer, posses the ability to look at other people's code. So I'm seeing createComponent when I'd assume the answer to this is yes, but I figured I'd be thorough and ask. |
|
Yeah I might even remove // consider:
<Component prop1="static" prop2={state.dynamic} />
// becomes:
sample(() => Component({
prop1: "static",
get prop2() { return state.dynamic }
}))Does that makes sense? Generally, ignore the memo it's for a special case in which the component returns a function. But I'm intending to solve that a different way in the future to avoid unnecessary wrapping. |
|
Good call on the interopt. Bringing other libraries into Solid is pretty easy but the opposite matters completely on the mechanisms of the host framework. For client side its mostly just a ref and As for generators no. The lifecycles are a bit fake anyway. Its all just reactive subscriptions. Tracking in generators doesn't really make sense to me and unclear what we'd be yielding to. I guess the settling of the reactive system. Not sure. Probably worth some thought. I wonder if introducing them core would create potential issues for concurrent rendering. |
|
@ryansolid I don't know if you looked into the effection library, which uses generators to have Structured Concurrency, but it got me excited about using generators to solve some issues I've been having. Composing concurrent microtasks seems pretty natural with generators. It also performs well, better than async await & is memory efficient over large iterators. |
|
Stuff when I started:
|
|
@btakita I imagine this would be a larger change. MobX has things like @pfgithub Did by chance you see the tutorials on https://dev.solidjs.com? I was hoping they would supplement the docs sufficiently. |
|
@ryansolid That makes sense. Thank you for the explanation. I am running into wanting to add an interface to the |
|
I agree we collecting some stuff in the Discord. I'm just uncomfortable writing it myself. I do not feel confident in my knowledge of TypeScript at all. Some people have contributed some very powerful typing to Solid but I feel after almost 3 years on TypeScript it still hasn't clicked for me. |
|
@ryansolid Just wanted to say that video yesterday was excellent for explaining the reactivity system. I think the interview format made all the difference, making the video an order of magnitude better than the current reactivity guide linked in the readme.md Linking that video in the documentation under something like "how does Solid know what to update?" would fill the biggest documentation hole for me (and would fully address my original message on this thread) |
|
Might be just me, but I think it would be helpful to include the import line required for each code snippet (currently done in some but not all of them) e.g. const [getValue, setValue] = createSignal(initialValue);
// read value
getValue();
// set value
setValue(nextValue);
// set value with a function setter
setValue(prev => prev + next);Could be 👇 import { createSignal } from "solid-js"; // adding this line
const [getValue, setValue] = createSignal(initialValue);
// read value
getValue();
// set value
setValue(nextValue);
// set value with a function setter
setValue(prev => prev + next);This would help newcomers like me who don't have the project structure in mind yet and help fly over the documentation a little faster. |
|
I know very little of React, mostly use Vue 2/3 and kind so kind of thought give Solid a shot (React didn't really stick because of all these immutable object updates and state management libraries). So thought about implementing a json form and kind of struggling understanding how to go about nested structures that update directly and in what form should I pass props. Let's say we have fields that could be retrieved via ajax: const fieldDefinitions = [
{
name: 'email',
type: 'string',
value: '[email protected]',
},
{
name: 'roles',
type: 'entities',
schema: [
{
name: 'name',
type: 'string',
value: '',
},
],
value: [
[
{
name: 'name',
type: 'string',
value: 'User',
},
],
],
}
];And we would just pass it to a SchemaForm element: <SchemaForm fields={fields}/>And it's implementation (just a sample): const SchemaForm = function (props) {
function dummyClone(array) {
return array.map(item => Object.assign({}, item));
}
return (
<For each={props.fields}>{(field, i) => (
<Switch>
<Match when={field.type === 'string'}>
<input
class="form-control"
name={field.name}
value={field.value}
onInput={e => field.value = e.currentTarget.value}
/>
Value Is Reactive: {field.value}
</Match>
<Match when={field.type === 'entities'}>
<h4>{field.name}</h4>
<For each={field.value}>{(entry, i) => (<>
<SchemaForm fields={entry}/>
<button type="button" onClick={() => field.value.splice(i(), 1)}>Remove</button>
</>)}</For>
<hr/>
<button type="button" onClick={() => field.value.push(dummyClone(field.schema))}>Add</button>
</Match>
</Switch>
)}</For>
);
};What's the reasonable way to pass All the samples so far were dealing with data structure you know and shallow tree but kind of wish there were samples of dealing with recursive data and their mutation. What would be the preferred Solid way? |
|
I think I've got a question that I really cannot understand. But it's only very-minor conceptional Why
|
|
Lots of frameworks have terms that aren't obvious which require reading documentation. In some cases the word and meaning between frameworks and patterns even overlap further adding to confusion. So consolidating terminology to align with other broad concepts isn't the strongest argument for calling it From a personal preference perspective I rather like signal, it gives Solid a bit more distinct of an API and also I feel like the word expresses the mechanical reactive nature of the primitive: when the value changes it signals a change in reactivity (tracked dependencies are rescheduled for evaluation). What makes it different is that the dependencies automatically re-evaluate when a change occurs. The automatic nature of evaluation is why I like signal better. If you're specifically coming from React I think this difference is very useful especially if you're new to reactivity. So responding to your point about it "feeling natural to using the framework" to me this does feel more naturally Solid. Lastly, state to me is a much broader term involving more than one part of the application. So state could encompass multiple components. This definition could be flawed but it's how I've developed my own mental model around Solid's differences. ie. state represents the wholistic state of the app. Is that fair to say? |
|
I've found a few bumps in the road learning Solidjs from the documentation that I think would really help people adapt more easily:
|
|
@KyleFontenot can you elaborate on #2? I've never heard any issues with CSS Modules. We won't mix the imports since Solid can support other non-web platforms. The Router does need much better docs. More it needs guides. The API isn't that large but so much in how you use them. |
Thanks for hearin me out! Unless there's something with syntax I'm missing |
|
Yeah you can use: import styles from './Component.module.css'
const Component = (props) => {
<div classList={{[styles.container]: true, alternate: props.alternate, }} />
}This JavaScript syntax lets you use a variable as a key to an object. In your other example it was setting |
While I agree with Ryan on this one, I think the opposite might be a solution to both concerns.(e.g. would it be possible to have There would need to be no name collisions between the two, but other than that it would allow the web side to have a single import, while also not locking 'solid-js' to a browser context. |
Stating something like "never destructure" in the docs would have saved me hours 😅. I searched the docs using google and couldn't find any mention of it:
|
|
@jsdevtom Like header worthy(outside of the FAQ) I guess? It's mention 5 times in the getting started section and 4 times in the docs. People have mentioned not seeing it though so it clearly isn't present enough. I feel like I mention it in every paragraph, but I get that. |
|
Ooh yes, I see that now. It's my fault for not reading the ... manual. I was rapidly trying to prototype with Solid because I didn't have the luxury of time. I assume others do the same thing. Perhaps UX could help. Something like an inline warning ~ https://design-system.service.gov.uk/components/warning-text/. Just a suggestion. As I said, it's my fault. It could help other (time strapped) individuals, though. |
|
I think when developers go to docs, the first thing they see should not be "Basic Reactivity" and "createSignal". Because these terms might not mean anything to them. There should be a getting started at the top of documentation. |
|
The intention was the "Getting Started" section to handle that. But maybe it's a naming thing. That section is more of an API reference and should be named as such. |
|
I think more information on some of the things that you can't do in solid that people might be used to from react - for example, top-level markup conditionals in a component. |
Do other frameworks do this as well? Mind linking us so we have an idea? |
|
I mean React supports top-level conditionals and early returns. The core team suggests that it is bad pattern but people still do it. You will find enough React code that does without looking hard. Frameworks with Template DSLs don't have the ability to do this so really this is a Solid-only problem from a certain perspective. It's obvious to us who understand the execution model but someone coming from React, Angular, Vue, Svelte, Ember, Inferno, etc would have never experienced this. It's probably worth mentioning the same way prop destructuring is. |
|
I think a "Thinking in Solid for a React/Preact developer" is probably what's best to have, and explain how the mental model and execution model is different. All the gotchas. |
|
@nksaraf There's a starting point: https://github.com/teknologi-umum/solidjs-for-x-developer/blob/main/React.md |
|
@millette @davedbase I had no idea this repo existed, what a great starting point. |
|
This issue has been great and has allowed not only better docs for Solid but the formation of a docs team. I feel like it has run its course though and I appreciate all the suggestions the last 2 years. Now that we have a dedicated organization and repo for docs all future suggestions should go there. https://github.com/solidjs/solid-docs Thank you so much for making learning Solid more enjoyable. |
and others
I really would appreciate feedback here. It is so hard for me to see it since I've been so close to this for so long and I've developed apps in this manner for 10 years. I'm going to be the worst person to write the documentation since it is all so second nature for me. Yet, I am most likely going to be the person writing the documentation since I understand how everything works so well.
So can you please comment on anythings you found confusing about Solid as you've been trying it out, using it in your demo projects, integrating it with 3rd party libraries. And if you did find a solution can you comment on what you feel would have been the easiest way to describe it to you. Even if it takes me some time to compile all of this I think it would also highlight some early gotcha's for people trying the library.
I know I need to do a lot better here but this is a bit of a blindspot for me. Thank you.
The text was updated successfully, but these errors were encountered: