component workflows

[sabob]

Here is PR for workflow. I ended up writing a bit more than I intended and covered managed vs unmanaged components as well. Use or ignore as you see fit :)

[evs-chris]

Nice!

[fskreuz]

I think most of the content could go in https://github.com/ractivejs/ractivejs.github.io/pull/73 since it's more focused on the "how to use" aspect than a "how to write" (which is pretty much the focus of the Extend section - how to write, how to register, how to use as fast as possible). This can be reorganized later though.

The docs have been rewritten to a third-person point of view (like a user manual) instead of a second-person point of view (like a blog). Second-person sounds chatty and tends to become long, fast.

Other than that, good exhaustive documentation of managed vs unmanaged. Could be shorter tho. 👍

[sabob]

To my mind the docs should be detailed because where do users get more info after that? The "Getting started" is a good place to get going quickly, while the API is good for references, but docs is really where in depth explanation can take place together with some context as to why you would need a feature eg. components, pros, cons pitfalls etc. But it also depends on the target audience, advanced users or beginners. Ideally after reading the docs, the user moves from beginner to advanced. Personally I like docs covering a feature in full so I can get a clear picture in my head, hence the inclusion of how components should communicate. Otherwise I have to dig around to understand how things hook up.

[fskreuz]

True, detail is good. But no one wants to be read a wall of words. It's the one big reason why most people ask in StackOverflow instead of reading documentation. It's the reason why people read W3Schools over MDN over the ES spec. People just want to get there and take what they need without reading 4 pagefolds of content.

I would think of API, Extend and Integrations as the same - a list of things to know in outline form, for API, extensions and tools, respectively. The Concepts section is where one should go if one needs an in-depth discussion.

[evs-chris]

People prefer w3schools over mdn!? I mean, the ES spec is painful to navigate, but mdn is pretty decent. I'm pretty sure w3schools used to kick puppies and duct tape kittens together in the dhtml era.

[fskreuz]

I used to know people who do it for "quick reference" because it comes up first in most searches (without prefixing MSDN/MDN/other sources). Their format is also beginner-friendly with one-paragraph descriptions and inline examples - pretty much where the Concepts section is headed. 😄

[sabob]

Perhaps components belong to both categories? Components seem like a core concept of Ractive.

[fskreuz]

Hey @sabob , I think I added your suggestion of managed and unmanaged as part of the workflows PR https://github.com/ractivejs/ractivejs.github.io/pull/73 . Does it look good or am I missing the target? 😄

[fskreuz]

Closing in favor of https://github.com/ractivejs/ractivejs.github.io/pull/73 .