lab.js
lab.js copied to clipboard
FelixHenninger
Setup interface tour/walkthrough
For new users, it would be fantastic to set up a tour of the interface to demonstrate its most important parts. In this issue, we'd like to lay the ground work: Set up the infrastructure and a simple proof-of-concept. We'll happily provide additional content separately (though of course we won't stop you if you'd like to work on this too!)
You'll probably want to look into the following things -- but don't at all feel bound by them!
- I'm not really sure where to start, so it would be awesome if you could briefly investigate and choose/recommend a library that you could use, possibly something like react-joyride or driver.js. It should be one that's well-maintained and that ideally fits in well with our bootstrap-based layout.
- Maybe set up a minimal walkthrough (just a single step will do) that is started from the welcome screen (whose code is in
packages/builder/src/components/ComponentOptions/components/Welcome). If you like, you're welcome add more steps to the tour; these don't need to be super-well thought out: We can, for example, add detailed text later, and we'd love to work with you to setup a sequence of highlights.
A quick heads-up: The infrastructure for this is now in place, and there's a prominent intro point on the splash screen that could be used to start a tour. Would be more than happy to get people started with this!
hey @FelixHenninger could you give detail about what infrastructure is now in place, and what you would like help to do? I had some quick thoughts when I was reading about this general need to education users:
- The goal is to get someone started using labjs.
- There are three ways I can think of to (obviously) go about this.
- The first is with documentation, and walkthough with screenshots. I could offer to help try this out if something substantial doesn't exist (it would help me to better learn) and to do this, I'd want to ask for help in just a basic outline of the steps I should cover.
- The second is (I think) what you are alluding to above - have some kind of built in pop ups / pointers that show up on the website. I'm a bit not in favor of this solution - I find these tutorials (almost impressive in terms of technology) sort of annoying, and mostly try to close the pop ups. It's also not totally easy to go back to - for example, if I forget a point in the middle I have to click through something again vs. easily going to a different link or page in documentation.
- The third way that I think would be useful in fun is for the kind of learner that wants to see the example, interactively. For this, we can use simple screen recording software (I know how to make videos that can show several screens at once and record the person talking).
Maybe it would be good to start with 1., go through the tutorial and guide, and then do 3 to make it interactive? The idea would be to address both kinds of learners! For both of these, I would want to draft a quick bullet list of points to cover, and then I would take a stab at the docs, and when they are satisfied (gulp) go for trying a video. I have another idea I'd like to discuss that is related that I'll put in another issue!
Hej Vanessa,
thanks so much for taking a look at this, I really appreciate your feedback! This is totally awesome, I have to admit that I didn't really think this through entirely.
I was imagining (and had started implementing in a local branch that I'm happy to share) something like the walkthrough on https://kamranahmed.info/driver.js/, with the idea of combining points 1 and 3 -- my hope was to build something that would provide an introduction to the interface, and narrate visitors through building their first experiment. But I can totally see how that would lead to the situation described at point 2.
I've uploaded my branch at https://labjs-beta-tour.netlify.com/, and you can see a basic example by clicking on "get started" > "take a tour" (it's only a single step, but maybe it illustrates the idea). What do you think, would this be worth extending?
Regarding documentation feedback, that's of course always super-welcome -- We have video tutorials in the documentation (and I'm just finishing a paper-style tutorial), and I love making this more helpful, so any thoughts and ideas are massively appreciated! I had the good fortune of being mentored this spring by the awesome Priyanka Nag, who works on the Mozilla Developer Documentation, and she argued strongly that video tutorials age too quickly, and that it's really difficult to recoup on the investment of effort. I've been looking for a middle ground between videos and text since, and my most recent attempt have been animations. I kinda like those, but they were almost more effort than the narrated videos!
I somehow remember that you started documenting the expfactory integration. Would you be interested in building a page around that? I'd be glad to help (though somewhat short on time this week).
Ok, sorry for the somewhat stream-of-consciousnessy Update, I hope this makes a tiny bit of sense!
-Felix
I just checked out the netifly branch and found the button - this is exactly the kind of thing that I was thinking of with my second point. It wouldn't be bad to have, but for a researcher actually wanting to design an experiment, the impulse is just to click through it (or ignore it all together). I think this approach is cool, but is harder to maintain, harder to share (I can't print out a document or send a youtube video and watch passively) so I'm not convinced it's the best. To answer your question - I would say maybe it would be good to add, but only after the other two approaches (and there is clear feedback that the additional is needed?) Off the top of my head, I can't remember one instance of a site that has this kind of click through walkthrough that I've ever done anything other than click through "to get to what I want to get through."
Oh that is very true, +1 on videos aging. The simple markdown docs (maybe have a repo just for labjs tutorials?) might be the way to go then? The animations do seem like too much effort.
Yeah! There is documentation for expfactory + labjs in this repo --> https://github.com/expfactory/expfactory-labjs I'd be happy to add a page (officially) around that, and also re-test things. Maybe a logical direction from there would be to setup the continuous integration pipeline I talked about, starting from labjs --> expfactory container --> circleci? I think I could do this on my own, and then show you.
To start me off (probably later this week - I'm traveling cross country!) could you point me to the place in the docs to start writing ?
Ok, thanks for your comments! I totally see the point regarding the walkthrough, thanks for your comments -- I'll be moving that down the todo-list.
Regarding the docs, I'd love to add the experiment factory! The docs site is generated with Sphinx. I'm guessing that it's easiest to work from an example -- you can look at the page syntax on GitHub. You can copy and adapt this page, and add it to the documentation tree through the superordinate page. There's also a snippet (that I'd be happy to extend) on how to build the docs locally for testing.
okay great! I think I'll be able to start on this later in the week - moving cross the country as of tonight / early tomorrow and well, I'll be in airplanes and stressing out about losing suitcases :) Chat then!
okay just adding this here for recording of links - I've started the docs for Expfactory and will be working on them here (draft --> https://github.com/vsoch/lab.js/blob/docs/updating/docs/learn/deploy/3b-expfactory.rst). I need to read up on building with node/npm and then preview, and hopefully I'll still have a PR within the week! If you think of anything you want to note / requests let me know and I'm happy to add.