Lowering the barrier to entry for Jekyll

[mattr-]

Moving the discussion about how we handle installation documentation / packaging / lowering the barrier to entry here from #1929

[budparr]

Hope this isn't off topic from how the conversation got started, but seems to me the biggest barrier to using Jekyll isn't for devs, it's for content creators.

I absolutely love working on text on my desktop and pushing it up to Github Pages—the real beauty of a SSG in terms of content—but that's pretty much out of the question for most site owners/production/creators. Prose.io is great, but not foolproof; there's no real error handling or working support for images. I even think the Github interface isn't that bad (with a bit of training), but there's no image handling there.

n.b. http://mixture.io/ and http://www.siteleaf.com/

p.s. Love the collections idea!

[jglovier]

Moving the discussion about how we handle installation documentation / packaging / lowering the barrier to entry here from #1929

cc @mhulse for his previously articulated thoughts/further input.

---

seems to me the biggest barrier to using Jekyll isn't for devs, it's for content creators.

@budparr VERY much agree re: learning curve for content creators. Would love to discuss that more, but perhaps in a new issue so we can keep this one focused on the barrier to entry on the dev side?

I've opened #1977 so we can discuss it more there. ✨

[mhulse]

cc @mhulse for his previously articulated thoughts/further input.

@jglovier, thanks for the reminder!

@mhulse would you care to submit a PR to the Jekyll doc site with some of that info that might belong there? The GitHub Pages section could be a particularly appropriate section to add any of that info that is missing. ✨ [via @jglovier]

I plan on collecting my thoughts and reading through the related issues this weekend. At the very minimum, I think I could contribute a few small changes to the docs as mentioned above. 😄

With that said, let me bombard ya'll with some random ideas:

1. Community-powered YouTube video playlist

   Out of curiosity, and this might be a silly idea, but has anyone considered making installation and developer videos? Maybe some sort of multi-part series?

   I've always thought the creators of Pagelines, a WordPress theme/"framework", have done a great job at this type of thing:

   PageLines Essential Training

   In terms of a Jekyll introductory/developer video series, I could envision (official) Jekyll blog posts/pages with embedded YouTube player; below each short video would be a summary of what was shown on screen (for those that don't have time to watch the video).

   Alternatively, a single blog page with a video playlist embedded might be more convenient.

   The Jekyll core team could enlist the Jekyll community to produce videos (maybe there would be an outline of topics that need to be covered) and then someone would simply add new videos to the primary/official Jekyll playlist and remove old ones as they become outdated.

   The series could cover everything from basic "getting started" topics to advanced techniques like Rakefile usages, hosting and/or the things @mislav mentioned: t, vagrant, heroku (as the host?), cane.

   I'm not sure if that idea would help to necessarily lower the barrier, but it could help to quickly shine some light on how people use Jekyll in terms of tools, environments, and techniques (from the most simple to the most complex use cases).

2. Animated gif screen recordings

   Other than a video series, I've always found short animated gif screen recordings to be of some help in understanding docs/technical blog posts. I personally use Pixen for this. Maybe there's an opportunity to create some of these looping animations to help illustrate some of the technical bits of installing/hosting/running Jekyll?

3. Weekly-ish community spotlight

   One page that I've found invaluable as a noob, was the sites running Jekyll WIKI page. I think one of the coolest aspects of Jekyll is that I can look at other people's code. This really helped me to understand how things work (for everything from file/folder naming conventions and liquid usage to custom plugins and Rakefile usage).

   Maybe there's an opportunity for the core Jekyll folks to pick a new site to "spotlight" on a semi-regular basis? For example, this "spotlight" could be as simple as pointing out a cool plugin or maybe a unique feature of a Jekyll site?

   In terms of how this would lower the barrier, the "spotlight" could be archived/organized in a way that could help a noob; for example, maybe the archived list of blog posts could be sorted (using a bit of Jquery) by date AND complexity level (or even operating system and host).

4. Jekyll trending e-mail

   Related to the above idea ... As a GitHub fan, I love getting the "what's trending" newsletter/e-mail each day ... I wonder if the GitHub API could be utilized to send out a "What's Trending" newsletter/e-mail that was specific to Jekyll sites/code only?

   As a recent noob myself, this type of e-mail content would be very helpful in that I could keep on top of the latest Jekyll sites to see what other folks are doing.

---

Not sure if any of the above is useful to anyone.

Either way, if I see something I could improve via the docs, I'll be back this weekend with a PR for review by the pros. 😄

[mislav]

The series could cover everything from basic "getting started" topics to advanced techniques like Rakefile usages, hosting and/or the things @mislav mentioned: t, vagrant, heroku (as the host?), cane.

Just to jump in and clarify a few things: the Ruby CLI projects listed above were pertaining to another discussion and have no relevance in this one. vagrant and heroku are examples of CLI programs done right by isolating their Ruby runtime environment from that of the user. It has nothing to do with barriers to entry, but with stability of running jekyll over an extended period of time on a single machine where the user also does Ruby development.

I support teaching users about advanced topics of bootstrapping Jekyll, but I don't think videos are necessary for that. Better installation guide (in writing) covering potential Gemfile usage and different approaches whether you're using GitHub Pages or latest Jekyll + plugins would be enough.

I wouldn't ever recommend hosting Jekyll sites on Heroku. It's an overkill for static sites. As a static host, I recommend https://getforge.com

[troyswanson]

It's really cool when people are so on the same wavelength that they have the same ideas independent of one another. @mhulse, regarding your first suggestion, check out jekyll/screencast#1.

[mhulse]

Just to jump in and clarify a few things: the Ruby CLI projects listed above were pertaining to another discussion and have no relevance in this one. vagrant and heroku are examples of CLI programs done right by isolating their Ruby runtime environment from that of the user. It has nothing to do with barriers to entry, but with stability of running jekyll over an extended period of time on a single machine where the user also does Ruby development.

My bad. My lack of experience with Ruby/the tools you mentioned is shining through. 😊

Sorry to drag you into this convo.

Anyway, thanks for the clarification and the other thoughts/contributions!

Better installation guide (in writing) covering potential Gemfile usage and different approaches whether you're using GitHub Pages or latest Jekyll + plugins would be enough.

That sounds like an excellent starting point to me. If you don't mind, I may cc you if I do a PR so I can get your feedback.

I wouldn't ever recommend hosting Jekyll sites on Heroku. It's an overkill for static sites. As a static host, I recommend https://getforge.com

Ah, good to know! I've only used Heroku a couple times, and I do remember it being a bit of leg work to get the ball rolling (I was trying to host webfonts at the time).

https://getforge.com

Thanks for the host recommendation! is there a WIKI page around here that has a list of hosts? Like, S3, GetForge, and GitHub? I wonder if somehow the installation instructions could also tie-in notes on alternative hosting locations (other than GitHub, for example).

It's so cool to see when people are so on the same wavelength that they have the same ideas independent of one another. @mhulse, regarding your first suggestion, check out jekyll/screencast#1.

Awesome! :+1: x :100: to that issue! :smile:

Looking forward to reading through that issue, and perhaps contributing, this coming weekend ... .

From that PR:

Maybe we should also offer a survey to get more info about where new users are coming from?

Though I did not mention in my last comment, that thought had crossed my mind as well. I really like that idea!

[Wolfr]

Just a FYI that I have a 40 minute intro on Jekyll on Youtube.

It's not high qual but a few folks have thanked me for it so I guess it has some value ;)

http://www.youtube.com/watch?v=O7NBEFmA7yA&feature=c4-overview&list=UUMs4dC8I8MqX-ZbfmSi0MAQ

[Wolfr]

Also made one about _data and more specifically about using Kimono to source the data:
http://wolfslittlestore.be/2014/01/kimono-jekyll/

[parkr]

@Wolfr Awesome, thanks for those links!

[qrush]

One interesting observation of this discussion: no one has addressed why the barrier exists (or what it is!)

Some thoughts on the why:

• Ruby is not trivial to install and manage
• Jekyll on Windows is a nightmare
• "All I want to do is write a blog post, why do I have to install X?" (ok, this is more existential)

Every project has to deal with this stuff. There's a barrier to entry for every software, ever. Identifying the hurdles is the first step to jumping over them.

Some thoughts on what could be done here:

• Consider supporting whatever the default Ruby on OSX is (or on various popular Linux builds)
• Don't support Windows. Let another project take over support for this or suggest web-only editing via Pages/Prose.
• Better documentation specifically focused on newcomers per platform. The current guide is extremely brief and not written for those new to a command line: http://jekyllrb.com/docs/quickstart/

Maybe I'm just spitballing here...but I'm seeing a lot of solutions offered without talking about the problems at hand first. Hopefully this draws more discussion out.

[qrush]

I just reread this thread and it seems like I missed the "mini-summit" mentioned in #1929. It would have been a bad time anyway with a one-month old newborn. The "vision" mentioned in that thread seems to clash with what I view Jekyll as. Perhaps my "vision" is outdated. That's ok though. Things change!

Maybe it's best if I just bow out and let the current captains continue to sail the ship, as they have been fantastic stewards so far. I need to concentrate my OSS time & energy anyway, and I'd rather do that on RubyGems. 😁 🚢

[ndarville]

Maybe we can organize a “Jekyll failathon” somewhere, not with the goal of finishing a product, but of learning how to fail the right way as a neophyte, and how to identify and solve those problem as a Jekyll pro?

It lowers expectations and hesitations on behalf of people curious to try out Jekyll, and it creates a good environment for asking for and providing help, which we in turn can use to identify the bottlenecks.

[parkr]

Working on a standalone install for Mac. https://github.com/jekyll/omnibus-jekyll

[jglovier]

@parkr Awesome!!