Closed dagnelies closed 7 years ago
evs-chris
commented
7 years ago I'm in the process of moving the learn.ractivejs.org content into the tutorials section of ractive.js.org, and it's much lighter fare. I think once that's in place we can rearrange the menus a bit to pull the heavier stuff more into the background. I think the primary docs pages should be the tutorials and the API docs. Would that help?
dagnelies
commented
7 years ago What is actually the long term plan? To move the "docs.ractivejs.org" to "ractive.js.org", or the complete site?
If it's the first, great! If it's the latter, I'd be a little sad actually. The interactive http://learn.ractivejs.org is absolutely great IMHO. It's what made me embark for ractive in the first place. Without it I wouldn't be here to talk about. 😉
fskreuz
commented
7 years ago Well, it's to consolidate all the sites to one repo. At the moment, Ractive is spread into different repos (home page, docs, blog, learn, examples). Keeping them in separate repos makes it hard to update content, appearance and configuration.
The end result may still be the same (have a section for learn, examples etc.) but at least they'll be updated in one place and not 5 or so different repos.
evs-chris
commented
7 years ago Yep. Maintenance is a bit painful with everything so spread out. I couldn't get the latest version of ractivejs.org to build, much less deploy.
As far as the interactive tutorials, we're trying to preserve most of the excellent experience from the out of date learn site. Take a look at https://ractive.js.org/get-started/tutorials/hello-world and let me know if it's at least passable.
fskreuz
commented
7 years ago The current theme isn't final btw. There's an issue to track restyling https://github.com/ractivejs/ractivejs.github.io/issues/16
dagnelies
commented
7 years ago Well, I hate to be party pooper, but I must confess that I'm wondering if we're going in the right direction here. From a bird's eye perspective, I've the feeling a lot of energy is spent moving from A to B, while instead improving slightly A might make wonders.
I mean, originally, you meant to move to "B" to make it more contributor friendly, but for example we're loosing the link "click here to edit page", so it actually worsens it. Same with the tutorial, the current version is really nice, until you boost yours to reach it, you'll have basically rewritten it. Is it worth it?
But most of all, I don't think it'll impact contributions. Perhaps the modularity of having different repos is not that bad. Perhaps a simple script could automate the build process too.
Yep. Maintenance is a bit painful with everything so spread out. I couldn't get the latest version of ractivejs.org to build, much less deploy.
That is indeed very problematic. Is there a ticket about it? Can I help you somehow?
What I consider problematic too, and I noticed since ages, is that all smaller ractive repos are rather unmaintained and "gathering dust". For example https://github.com/ractivejs/Ractive-decorators-sortable has 10 PRs, several years old, and the plugin stopped working after v0.6 or so. In other words, as soon as someone digs in Ractive, they'll quickly encounter that most plugins are outdated/unmaintained, even the "official" ones.
fskreuz
commented
7 years ago I don't think it'll impact contributions. Perhaps the modularity of having different repos is not that bad.
If you only have a handful of people maintaining it, it's that bad.
I've the feeling a lot of energy is spent moving from A to B
Yep. But that's a one time deal.
After completion, the effort of maintenance won't be multiplied by the number of repos anymore. If the docs change layout, you don't have to update 5 different repos to make them look the same. If Ractive updates, you don't have to update 5 different repos and check if the examples still work in each. If you need to update explanations, you don't have to update 5 different repos to see if the explanation is coherent with each other.
but for example we're loosing the link "click here to edit page"
Again, we're not losing it. Part of the theme change which is ongoing. If you look at the current Ractive site compared to say Inferno or Vue, which framework would a newbie choose? The one that looks squeaky clean and complete? Or the one that's not been updated for a year and looks dead on Github?
What I consider problematic too, and I noticed since ages, is that all smaller ractive repos are rather unmaintained and "gathering dust".
Again, another issue arising from being split in multiple repos with only a few people maintaining. This also digs back up the conversation about mono repos which I'm recently considering (when I get around to learning Lerna). I only hesitate since we still publish to Bower which likes the multi-repo approach.
fskreuz
commented
7 years ago Hey @dagnelies , we've merged API, Extend and Integrations sections to one page each. It's sort of simpler on the menu side of things, but the pages are longer. Wondering if we can get feedback from you.
Also, we're on gitter for the most part. Feel free to chime in. 😄
dagnelies
commented
7 years ago Given my foggy memories, it's always difficult to be totally objective since I don't remember exactly the state it was.
That said, I have the feeling this is definitely going in the right direction. Before it was "waaaaaah, tooo much!" ...and now it's "hmmm ....there is a lot". 😉 The content looks good though. ...it only feels quantitative 5x the original docs.
Given that ractive is very easy to pick up and get started, which is IMHO one of its greatest strength, the thing that makes me a bit sad is that the docs make it look like a huge complex beast with tons of material to read first ...and that's really a thing we should avoid IMHO.
I'm a bit tight on schedule to work on suggestions or discuss it in lengths but I'll try to find some time soon.
fskreuz
commented
7 years ago Documentation now updated
There may still be some pages that are too long or need rewording. But I think this will be the general structure of the docs that will cover the needs of a newbie, a regular dev, a plugin builder, an integration builder, a contributor and a lost user... respectively. 😄
Feel free to extend the discussion tho.
Hi,
IMHO the "new" documentation is fairly daunting. It feels overwhelming. 😯 Please don't take it as a critique, it's just sooo much content. I've no silver bullet for that either.
🤔 🤔 🤔
Perhaps making it more "goals oriented" rather than a dry reference, and moving all the technical stuff a bit deeper.