These are chat archives for ractivejs/ractive

28th
Apr 2017
Joseph
@fskreuz
Apr 28 2017 14:18
PSA: The new site (https://ractive.js.org/) is open for design ideas btw. :smile:
At the moment, while docs are being updated, it's just using some generic bootstrap-y theme. It can be better.
Chris Reeves
@evs-chris
Apr 28 2017 17:23
for those designer-y people interested, a good start would be something to make the index look a bit less like a "docs only" site
Joseph
@fskreuz
Apr 28 2017 17:23
Was leaning towards something like inferno's homepage :D
white with green highlights, alternating bands of white and light grey sections, preserving the two fonts the site uses
https://fonts.google.com/specimen/Voltaire
https://fonts.google.com/specimen/Source+Sans+Pro
Chris Reeves
@evs-chris
Apr 28 2017 18:49
it's definitely less bootstrappy, which I like :smirk:
getting the menu background to black or white would probably help
Juan C. Andreu
@andreujuanc
Apr 28 2017 18:51
I do like the current landing page
the interactive demo is really nice.
It's actually what made me try ractive.
I hate text, xD i want code and demos .
60 second setup is amazing
and tutorials are really good to start
everything on js.org is more text and reading D:
:confounded:
Inferno is ok, but it does not shows your what it does. Yes, it says what it is, but not really .
You have to scroll down to find it
Joseph
@fskreuz
Apr 28 2017 18:56

everything on js.org is more text and reading

It's actually the same content as what's on the existing site. :D

Juan C. Andreu
@andreujuanc
Apr 28 2017 18:56
No no!!
Order matters
also tutorials are different
interactivity is key
Joseph
@fskreuz
Apr 28 2017 18:58
That part was changed. But if you check the other pages, particularly the concepts portion, it's the same stuff.
Juan C. Andreu
@andreujuanc
Apr 28 2017 18:58
yea yea
Evaluate the landing page
Get started in 60 seconds link is good
and the interactive demo is great. For sure it can be improved , but personally i think it's a nice approach
Joseph
@fskreuz
Apr 28 2017 19:00
The one thing lacking in Ractive which I find in abundance in inferno (and vue) is that they have concise API docs.
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:00
Docs are hard to write D:
Joseph
@fskreuz
Apr 28 2017 19:01
But true, the js.org is too docs-like. :thumbsup:
Anyways, was about to write earlier that mkdocs is just another static site generator. We can ditch it for another tool provided that the replacement:
  • consumes vanilla markdown (or at least gfm, for fenced code)
  • does not clobber {{ }} (*cough* gitbook *cough*)
  • does not get real hairy after say... 2-3 years (I couldn't even get the homepage repo built locally)
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:04
:clap:
What other options are there out in the wild?
Joseph
@fskreuz
Apr 28 2017 19:08
A lot. I just went for mkdocs because all that's needed is a text editor with preview. You don't need to set up the site locally to write docs.
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:09
I have never used github
Is it cool?
Joseph
@fskreuz
Apr 28 2017 19:10
you mean github pages?
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:10
Sorry! haha. Muscle memory xD
Gitbooks!!
Github pages is alright.
Joseph
@fskreuz
Apr 28 2017 19:11
Oh, redux uses gitbook. It's cool... until the part where you discover that it treats stuff in {{ }} as interpolators. Not good for us where {{ }} is literally everywhere.
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:12
Oh jesus
xD
Now i get your coughing xD
Joseph
@fskreuz
Apr 28 2017 19:12
Their solution is to wrap it in {% raw %} and you don't want to do that everywhere.
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:15
JSDoc can be good. I think I read somewhere month ago that it's really plugin friendly.
Very extensible.
Chris Reeves
@evs-chris
Apr 28 2017 19:19
I think the issue with things like jsdoc is that they're more code api focused, like javadoc
Joseph
@fskreuz
Apr 28 2017 19:19
Java-like, auto-generated docs aren't really the prettiest out there. :D
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:19
:shipit:
Handmade then?
Chris Reeves
@evs-chris
Apr 28 2017 19:20
I'm having a hard time coming up with useful tutorials that actually cover all of what needs to be covered
handmade md seems to be the most reliable
with low barrier to entry
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:21
Tutorials the way they are now are good. And I mean the interactive ones. I think it's good enough to get you started.
I think it does not have to cover everything.
But then, API Docs it's different.
Chris Reeves
@evs-chris
Apr 28 2017 19:21
learn.ractivejs.org ones or the ones on the js.org site?
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:21
learn.ractivejs.org
Loved those
Maybe someday there will be a Ractive University, but for now that really get you started. And fast.
It's faster than reading docs and do everything locally.
Chris Reeves
@evs-chris
Apr 28 2017 19:23
was shooting for having examples inline in the api in the same format as the tutorials
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:23
Then you go and start a project with it. And when needed , API Docs should be easy to read, short , and with example
Oh jesus, that would be amazing, but I think it's not necessary.
Chris Reeves
@evs-chris
Apr 28 2017 19:24
would it be better to just make a tutorial page for each section on the learn site?
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:24
If you are reading Docs it's because you already know how things works. And just looking for the name of a function or what parameters to use, etc
What do you mean?
Chris Reeves
@evs-chris
Apr 28 2017 19:26
instead of trying to do in depth tutorials around each section of ractive - overview, contexts and keypaths, computations and expressions, template constructs, events, components, etc
just do the learn tutorials
Joseph
@fskreuz
Apr 28 2017 19:26

If you are reading Docs it's because you already know how things works.

Not really. I often scan the docs to look for something new that @evs-chris might have added, or looking for better APIs to do stuff with. :D

Chris Reeves
@evs-chris
Apr 28 2017 19:27
it's basically merging the concepts and tutorials together
it might be too chewy though
the learn stuff is all fairly light, but it's more than a bit out of date and sorta awful on mobile
not that I expect a whole bunch of people to try to learn ractive on phones :smile:
Joseph
@fskreuz
Apr 28 2017 19:29
speaking of the learn site, i read https://help.github.com/articles/user-organization-and-project-pages/ and it looks like it allows projects under an org to be a subpath of the org. i.e orgname.com/project.
Chris Reeves
@evs-chris
Apr 28 2017 19:29
it just doesn't seem right to have the docs so far separated from the learn stuff
Joseph
@fskreuz
Apr 28 2017 19:29
wondering if learn could be ractive.js.org/learn if we renamed it to "learn" and ractive.js.org/playground be the actual playground repo.
Chris Reeves
@evs-chris
Apr 28 2017 19:31
I'd rather have it more closely integrated into the docs
Joseph
@fskreuz
Apr 28 2017 19:31
:thumbsup: gotcha
Chris Reeves
@evs-chris
Apr 28 2017 19:31
do you think the playground is sufficient for that?
Joseph
@fskreuz
Apr 28 2017 19:32
I think the inline button + playground pop-up is fine. the pop-up just needs a bit of exposure tho. :D
maybe a "try it on playground" text, similar to lodash's "Try it in REPL" which opens runkit.
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:46
+1 for try it on pg
without redirects? :fire: !!

instead of trying to do in depth tutorials around each section of ractive - overview, contexts and keypaths, computations and expressions, template constructs, events, components, etc

I get you, but I think tutorials follows a different order than api docs.

Unless somehow a nice ui design makes me eat my words
Tutorial goes first on basics. Mustaches, properties, etc
Chris Reeves
@evs-chris
Apr 28 2017 19:48
ui design is definitely not one of my strengths
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:48
And Docs goes on init
Joseph
@fskreuz
Apr 28 2017 19:50
Btw, there's a thread for the style refresh ractivejs/ractivejs.github.io#16 . Suggestions are very welcome. :smile:
Juan C. Andreu
@andreujuanc
Apr 28 2017 19:51
IMO Tutorial, Api docs, and Playground are 3 different things. for sure, they all complement each other. and should be linked when possible.
Joseph
@fskreuz
Apr 28 2017 19:54
one other problem is that... all of those are currently spread in a handful of repos. the other goal of the new site is to consolidate all of them in one place so they're easily updated. :)
currently, if ractive updates to a new version, home page resides in one repo, the docs in another, learn in another, examples in another...
Joseph
@fskreuz
Apr 28 2017 20:00
that doesn't include the tools and plugins which still believe it's still 0.7 :scream:
Chris Reeves
@evs-chris
Apr 28 2017 20:00
yep
I still haven't gotten round to forming a ractivejs npm entity and asking Rich to grant access to it for all of the various npm modules
I never really used rvc and friends
most of the plugins are still compatible across versions though
Joseph
@fskreuz
Apr 28 2017 20:02
backwards compatibility FTW! :+1:
Juan C. Andreu
@andreujuanc
Apr 28 2017 20:03
+1
Juan C. Andreu
@andreujuanc
Apr 28 2017 20:16
when you feel not creative: http://colormind.io/template/paper-dashboard/
:smirk:
image.png
Just generated that using a picture of me as a source xD
Juan C. Andreu
@andreujuanc
Apr 28 2017 20:21
I do like the gitter gradient tho.
Just a small contribution. I asked my wife for her opinion, since she is photographer/designer, and said that those on ractivejs/ractivejs.github.io#16 are nice but gradients are so subtle that might make you think there is something wrong with your monitor.
Joseph
@fskreuz
Apr 28 2017 21:09

Just a small contribution

Size doesn't matter :thumbsup: Any form of contribution is welcome :D

Juan C. Andreu
@andreujuanc
Apr 28 2017 21:19
:sparkles: