Survey for you beautiful people

[troyswanson]

The gardens of Jekyll are bountiful and lush, but the road to getting there may sometimes be rife with obstacles.

I came up with a quick survey that will hopefully help identify the primary pain point that folks run into when giving Jekyll a tumble. I believe @parkr will convert the question into a web form that will be tweeted, hopefully giving us some actionable data to better curate content for a typical new user.

Any suggestions that might improve response rate or glean better data are more than welcome.

---

What was the most challenging obstacle to overcome when getting started with Jekyll?

• Overall concept (file-based CMS, static rendering)
• Installation (installing the Jekyll gem and all dependencies)
• Configuration (directory and file structure, YAML front-matter)
• Templates (creating HTML layouts, using Liquid)

[Wolfr]

• Working with YAML was the hardest for me. I kept getting weird errors.
• Getting to know Liquid was also hard as I had no experience with similar templating languages
• I ran into some problems with gems and rvm but this had nothing do with Jekyll itself (although it's an obstacle)
• I found the docs lacking in clarity/depth but this was before the new Jekyll site which is so much better
• When you google for tutorial you used to land on some dodgy site, it seems much better now, there are some new (sometimes commercial) resources available.

[parkr]

@troyswanson Think we should just push out this one question, or should we flesh out another few questions (maybe 2-4?) to gain broader insights?

[troyswanson]

I don't really know. I was hoping for more response in this issue, tbh. Might be worth it to just push this one question and come up with a more focused follow-up question later based on the initial responses.

Less questions = less friction = higher response rate

[mhulse]

I tried to answer this earlier, but I quickly found myself writing a novel.

The original question kinda looks like a multiple choice. Maybe it should read "pick one (or, the most important one to you), and then tell us why".

In terms of polls, Google Drive forms are really easy to bust out (plus, you get free spreadsheet goodness). I have not tried, but there's also WuFoo for form building, which look nice. SurveyGizmo I've used for multiple choice stuff. We use CivicScience at work for polls. Really though, Google Drive will give you the most bang for buck; it's embeddable and free. :+1:

Then again, there has to be other free poll tools out there that will help to streamline this process. Anyone have recommendations?

I don't know stats for the Jekyll homepage, but I wonder if there could be some sort of "Attention all users, fill out this form" call to action box?

Sorry if I'm not making sense here. I've had a few brews and it's late. :beers: :laughing:

I'll swing back by later with my answer. Just need some time to think about the question.

[troyswanson]

@mhulse Thanks so much! The main goal of the question is to find out the main problems folks deal with when getting up and running so that we can create some video tutorials to help get them started. I like your addition to the question and the open-endedness of an optional free response field.

@parkr has mentioned something about using PollDaddy which seems like a good option, and I assume he already has an account. I think modifying the home page to add a link to the poll is a great idea if the community is down for it.

For a guy who's had a few :beers:, your response was excellently written. Thanks again! :heart:

[parkr]

For all interested parties: http://jekyllrb.polldaddy.com/s/what-was-most-challenging-obstacle-to-overcome-when-getting-started-with-jekyll

[madhur]

Submitted.

[ndarville]

@Wolfr

I ran into some problems with gems and rvm but this had nothing do with Jekyll itself (although it's an obstacle)

Well no and yes. I think it’s good that you bring this up, because we have to face that Jekyll might be many people’s first exposure to Ruby—heck, it might be people’s first foray into programming after relying on non-technical CMSes like Medium, Tumblr, and Wordpress.

Maybe there should be a guide for idiots like me who want a virtual environment so I don’t have a different result in production versus development, because I have some old gems lying around. Doesn’t mean everyone has to read the guide; it can be there as an Intermediate guide for those interesed and who may not have a Ruby background.

You never know how many adopters you lose out on, because they run into a brick wall at a step that people don’t formally recognize as their area of responsibility, but we might as well own the whole experience stack, so to speak.

[troyswanson]

a guide for idiots like me who want a virtual environment

If someone is approaching Jekyll from a non-technical perspective, I'm not sure if a virtual environment like vagrant or docker is the way to go. I'm a developer and that stuff blows my brain into a million tiny pieces. I suppose I could be convinced, though.

Just my two cents. :smile:

[ndarville]

Not like that, but like virtualenv for Python to isolate dependencies, and whatever fits those criteria for Ruby.

[mhulse]

I love the idea of seeing more Ruby dev tips and tricks.

Environment stuff, plugin dev. Ruby basics in relation to Jekyll. Command line usage (debugging, API calls?).

Not like that, but like virtualenv for Python to isolate dependencies, and whatever fits those criteria for Ruby.

+1. Isn't that what Bundler is for?

[parkr]

I think @ndarville has a good point – it'd be great to have a "Getting Started with Jekyll and rbenv" or something. It could give you a simple script to run which:

1. Installs rbenv
2. Installs useful plugins (i.e. rbenv-gem-rehash)
3. Installs Ruby 2.1.0-github if using GitHub Pages
4. Installs bundler
5. Runs bundle install

Boom, bootstrapped. Only thing we can't help with much is Xcode stuff, but we could take a cue from Homebrew.

[ndarville]

If anyone wants an example case where this matters, my own issue was complicated by different gems on development and production. We should employ a similar example to explain people why environment lock-down is important, when we write the guide.

At this point, it’s possible we might want to branch this discussion into a separate issue, though. :)

[parkr]

it’s possible we might want to branch this discussion into a separate issue

@ndarville Would you do the honors? :)

[ndarville]

You know what they say about cache invalidation and naming things ...

[tedsanders]

I'd say installation was the biggest hurdle for me, speaking as an amateur Windows user. I couldn't get things working the first time, so I gave up for a few months. Installing Ruby was confusing, gems were confusing, and bundler was confusing. It didn't help that I was new to Ruby and command line, especially since many instructions were for *nix systems. An additional straw on the camel's back is that the current version of Jekyll (1.4.3) comes semi-broken for Windows users. So in conclusion, installation was most challenging. :)

The concept of a static site generator seems simple enough to me (speaking as someone who knows basic HTML), and the other options -- configuration and templates -- seem easy to learn in a gradual way. The binary 'working or not' aspect of installation seems to make it the biggest pain point, imo.

[ndarville]

Maybe we should do another survey—or a HELP! page—to figure out where in the installation stack people get stuck on Jekyll:

• Using the CLI
• Installing Ruby (Windows vs. Mac)
• Installing Gems
• Using jekyll in the CLI for building and serving
• Customizing templates
  • General templates
  • Page-specific templates
  • Post-specific templates
  • Pagination
• Writing and publishing posts
• Sitemaps
• XML

Hell, maybe help people find help using Stack Overflow, IRC, GitHub, etc.

That way, we could expand the Docs or a Wiki based on the bottlenecks to using Jekyll. We could also create a script to generate a question to be used on Stack Overflow, IRC, etc.

Just throwing a suggestion out there.

[parkr]

@ndarville Want to throw something together? Please open a new issue!

[doktorbro]

@jekyll/owners: can be closed. We have a dedicated Help repository now https://github.com/jekyll/jekyll-help