Tweak upgrade steps #27
Conversation
|
WDYT @myronmarston |
|
This is definitely cool. I wonder if we should take it a step further and record the upgrade process using https://asciinema.org/? In fact, we could do the same thing with the example bowling spec on the home page. I decided to try out recording something to see how it turned out and it works really well: https://asciinema.org/a/13953 One potential downside if we go that route: while it's easy to embed the recordings in any page, I can't find a way to get the full assets such that you would no longer be dependent on that site -- so if that site ever shut down we'd have to find a new solution or change back to static code snippets. Still, it's cool enough that it's probably worth risking that. Thoughts? If we want to go that route I'm thinking I could take a project like https://github.com/seomoz/interpol and go through the upgrade process following our step-by-step instructions, recording each step along the way. That project is a good candidate for this kind of thing because it's open source, uses a pretty broad swath of RSpec, and has a pretty fast test suite (just over a second). It's already been upgraded to RSpec 3 but I could make a new branch off of the point the project was on 2.14 and re-do the upgrade steps from there. |
| <code>expect(list.size).to eq(3)</code>. | ||
|
|
||
| li | ||
| | Install transpec, this will save you a heap of time. (Note that this need |
There was a problem hiding this comment.
The sentence "Install transpec, this will save you a heap of time" reads to me like a run-on-sentence. I was always taught in school that this is a big-no-no (at least for formal writing), although I've noticed them more than a couple times in stuff you've written, @JonRowe :). I think our docs and site will read better without them. Maybe this could be "Install transpec, as it will save you a heap of time."?
There was a problem hiding this comment.
The style was deliberate because I wanted it to be a bit more casual and narrative, I personally prefer it as I think it's a bit easier to read.
There was a problem hiding this comment.
Run on sentences don't read more casually to me. IMO, it sounds uneducated and sloppy. For me, it's a bit like listening to music that's out-of-tune...it grates on me to the point where I pay more attention to the fact that a run-on-sentence was used than to the point the author is trying to make.
While I can't say how much of our audience will have a similar reaction, it's going to be a distraction for at least some portion of the audience.
You can just change the comma to a period or semicolon if you really don't want to add a connecting word like "as".
|
BTW, what are your thoughts on using asciinema, @JonRowe? |
|
I like the idea, it'd be need if we could convert the videos to gifs (if only for compatibility reasons) or something... It's not actually too difficult to record screens ourselves and then gif them... |
|
I recorded the entire sequence of videos: https://asciinema.org/~myronmarston I'll work on updating this PR with those videos another day. As for the idea of using gifs -- what asciinema does isn't just a video. It remains as text (you can pause the video, and copy commands our output out of it!). It's actually manipulating the DOM. We can't get that kind of flexibility with gifs. |
When RSpec 4 comes out, we'll have a different upgrade page. Making the link `/upgrading-from-rspec-2` will future proof this link so that it can stay up at that URL long after RSpec 4, 5, etc have been released.
|
Ok that's cool |
|
OK, @JonRowe, want to take a look at it now? |
|
I also pushed videos for the home page because I think it demonstrates the bowling example better than static text. |
|
So I like the console steps, but I feel the "coding" aspect of the videos is a bit slow and overwhelming. Is there a way to pick a specific frame for the videos so it looks similar to the original, but people can still watch all the way through? |
We can speed up the videos. I set the speed to
Not that I know of. The embedding docs don't mention anything about that. I'll reach out to the asciinema folks to see if they know of a way or have that planned. |
|
Hmm, sounds like there's no way for us to do this but the creator of asciinema has volunteered to update the frame shown for our videos if we send him the ids and times: https://twitter.com/sickill/status/535522478433771520 Before asking him to put effort into doing that for us, I want to make sure you're fully on board with using the on the site (I'd hate to ask him to change it and then have us wind up not using the videos). |
|
So I went through the videos to figure out what time in each has what we want displayed. Here's what I've come up with:
|
|
Yeah I'm on board with using them, maybe less of them than we had pictures though, what do you think about limiting them to maybe 1 (or 2) on the homepage? (Just going all the way through the process). Also thinking about the upgrade steps here, maybe we can create a presso type 1 video, and then just a shorter set of steps for those that don't want to watch something |
I think the description of the steps of TDD with RSpec has value, and videos showing those steps have value. If you can find a way to re-organize the steps into a smaller number of steps, I'm happy to re-record the videos.
I'm not sure what a "presso type 1 video" is. Personally, I'm pretty happy with the videos for the upgrade (now that I sped them up). Those that don't want to watch something don't have to. |
|
Merging as-is. We can improve this further in other PRs. |
|
It does look pretty sweet with the videos. |
|
Hey, asciinema creator here. First, I'm glad you liked asciinema ❤️ As for the "lock-in". I am working on separating the recordings (and player) from asciinema.org site so you will be able to download static "bundle", containing both the player and asciicast data, and put that on your site. I can't give you ETA as not everything has been figured out yet, but it's one of the priorities. I'll let you know. Meanwhile asciinema.org is not going anywhere :) Gifs... this is also coming, also on the todo list, together with snaphot png (to be used in github READMEs etc). No ETA too, but it will eventually be there. Note that, as @myronmarston noticed with gifs you loose the ability to pause, rewind and copy/paste. @myronmarston I'll update the snapshots to the exact times you listed (or maybe I'll just add the option for doing it by yourself to the site). Hang on, I'll keep you posted. |
|
Thanks, @sickill. Asciinema is really perfect for the new RSpec website as it works so well to demonstrate how to use RSpec :). |
|
@myronmarston I've added ability to specify snapshot frame time. See here: https://asciinema.org/a/14083/edit . I've set this one to 4.0 sec. Feel free to set times for mentioned asciicasts to your liking and let me know if you encounter any issue. |
|
@sickill That's fantastic. Thanks so much. @JonRowe -- I updated the snapshot frame for each of the videos (both on the homepage and the upgrade guide). Check them out now and see if you like what I chose. I tried to always show what the user would type along with as much of the output as would fit. |
|
Works for me :) |
|
👍 for using asciinema |
I took a stab at tweaking the upgrade steps a bit. See:
