Replace Jekyll with Phoenix

[doomspork]

As I announced in my OpenCamp's talk today, we will be migrating from Jekyll to Phoenix to support new features and improve the internationalization efforts (see: gettext).

Features we'd like to support:

• Better internationalization efforts
• Interactive exercises and examples (see: ExPlayground)
• Download as PDF book

Issues

These are the Issues we will address as part of the Phoenix project, list is expected to grow:

• Moving through lessons at bottom of page (Moving through lessons at bottom of page #95)
• Update README.md & INDEX.md (Update README.md & INDEX.md #194)
• Come up with solution to the 404 response surge (Come up with solution to the 404 response surge #247)
• Design and Front end implementation of 404 Page (Design and Front end implementation of 404 Page #278)

[brain-geek]

Wow, that's awesome!

@doomspork ping me if I can help!

[Exegetech]

@doomspork I'd love to help

[ybur-yug]

@doomspork so breaking this down I think we could potentially have a really simple, elegant system. Just some first thoughts...

1. We probably should make an umbrella. If we put the gettext stuff we do in its own section we not only get free isolation but we could eventually extract it trivially to be its own library if we came up with something cool on top of just the normal functionalities. With how many languages we have there is a lot of configuration work.
2. On that note, I think doing anything from simple scripting to generate the gettext-ified lessons out to phoenix templates to possibly maybe even making a small library to convert them and get them prepared properly and migrated from jekyll. That could be a total yak to shave but maybe interesting too. Hm.
3. The as PDF option is simple enough. If we just add a docker container that runs pandoc we can do the conversions easily with the generated markdown. Theres other approaches but in the few times I've had to do this, this solution was easily the most simple and easy.

Have anything to reference for idea w.r.t interactive stuff?

[moonrich]

WoW!! That's good news

[doomspork]

I'm excited to see so many people excited!

@brain-geek, @christiansakai I most certainly welcome your involvement. Let's use this issue to hash out the details. Once we know how we want to tackle this we can break it up into reasonable sized chunks and create issues so people can get involved.

@ybur-yug great minds think alike! There's going to be more churn on the translations so having them live in their own repo and app would be helpful in reducing the noise on the Phoenix application's repo.

I'll look for some of the interactive examples I've seen online and we can throw around ideas as well.

[Exegetech]

@doomspork thanks! I'm excited. I've been learning Elixir and Phoenix, played around on it by creating basic apps, SPA style and server rendering in Phoenix, but its pretty basic, so I'm not a Phoenix expert. Please guide me.

[michalvalasek]

Great idea, I'd love to help!

One comment tho: I'd be cautions with the docker stuff as it's quite an obstacle for new people wanting to get involved in the project. It might sound trivial for an experienced docker user, but believe me - it's hard for a beginner, especially on Mac.

[ybur-yug]

@michalvalasek can you elaborate on the specifics of what makes it difficult?

Our policy in the shop I work at is to do a few things to ensure that its as approachable as possible.

1. Provide a Makefile that handles deployment, running the server, tests, db creation/seeding/etc with simply commands that is platform-agnostic
2. Make sure everyone uses docker toolbox & docker-compose so were on the same commands-page
3. Have a wiki that documents everything.

Even with intern-level employees we've been able to get this running. But were a small, distributed-but-quite-communicative team. So, that definitely has a component to it and its much smaller than the number of contributors here etc.

By no means does everything HAVE to be docker, my comment RE that was basically just something that we could get as a free nice-to-have if we went that route. Personally, I see it as overengineering much of the time and moreso a tool for deployment than development. For development, I prefer something more turn-key like Vagrant if its needed at all.

[michalvalasek]

@ybur-yug Not everyone knows and uses docker. As someone new to docker you first have to learn about all the concepts (virtualization, docker images, docker containers), relations between them and finally all the tools involved (virtualbox, docker, dinghy, docker-compose). Sure, you can copypaste some commands from the README to your commandline, but you'll be stuck at the first divergence from the happy path. And that will happen 100%.

It's probably OK if you're in a company where other team members can teach you and help you with the new workflow and tooling. Even if you're remote. But it's a problem when you're alone just trying to get involved in the project.

I'm starting to sound quite negative, but all I'm trying to say is that I think the project should stay as approachable for outsiders willing to get involved as possible :)

[ybur-yug]

@michalvalasek I agree wholeheartedly.

By no means does everything HAVE to be docker, my comment RE that was basically just something that we could get as a free nice-to-have if we went that route.

I was just saying that there was one specific case that it would offer a nice addition easily if we were to be using docker.

For development, I prefer something more turn-key like Vagrant if its needed at all.

And when I said this I met something along the lines of discourse. If you check out their docs, the vagrant setup is actually really, really beautifully simple and takes no special expertise to pull off. Vagrant really abstracts all the hard parts. You can check it out here to get an idea of what the developer setup process is like.

I personally have found it really rewarding and it let me dive into the project and rework some things in a super fast/easy way when I first wanted to do this and didnt know squat about setting up and running a nontrivial ember app but had the API side of things down much more so.

So I guess IMO the best way to do it would be to have reliable instructions from a vanilla README but also if possible something as simple/turn-key as Vagrant.

[doomspork]

I want to begin laying the foundation for this but am unsure of the UX/UI, is anyone familiar with a designer who might be interested in lending a hand?

[ybur-yug]

My buddy @caleblummer and I are hacking on a Phoenix side project and he might be interested, we've both been talking heavily about giving back since were rolling with Phoenix for several parts of the app. You can check out some of his stuff @doomspork.

[runlevel5]

@doomspork I am unsure if this is better than Jekyll. A static site is much simpler to deploy, to put in S3 for CDN dist, and comes with less maintenance and less prone to hacking. Phoenix solution requires much more devops work, to me it is overkill solution of which rewards are not as equal as the effort to port it. Just my 5 cent

[doomspork]

@ybur-yug he is quite talented!

@joneslee85 you do raise a very valid point. As it currently stands I think Jekyll is sufficient but if we want to expand the feature set of Elixir School I think we have to look elsewhere. Some of the things on my "dream sheet" of features:

• Interactive Elixir-in-the-browser examples and exercises
• User accounts for users who wish to track progress
• Allow a user to select a language and download Elixir School in it's entirety as a digital book
• Elixir help / support (maybe this is covered by elixirforum and others)

What do you think?

[brain-geek]

@doomspork

Interactive Elixir-in-the-browser examples and exercises
This can be implemented as a separate subdomain, like try-elixir.org.

User accounts for users who wish to track progress
Would it bring a lot of value? I don't think we are going to compete with something like CodeSchool.

Allow a user to select a language and download Elixir School in it's entirety as a digital book
This can be done with Jekyll too. Those 10 PDFs can be generated automatically on deployment.

Elixir help / support (maybe this is covered by elixirforum and others)
It's a valid point, should we cover this? It's already covered by existing projects.

Anyway, is there any point of dropping current Jekyll solution? We can implement those one or two features in Phoenix while leaving current solution in place.

[doomspork]

It looks like the epub/pdf portion of this may be handled by a third party! I was recently pinged by a project (http://javier.xyz/docs2epub/) looking to process Elixir School into a book which we could make available ourselves. Within the next week or so they'll send me over the initial run so we can provide feedback on improving the final product.

@brain-geek you're probably right, Jekyll does the job quite well. If everyone is happy with Jekyll we can stick with it 😀

I would like to figure out how to incorporate more interactive examples in the lessons and how we might make translation easier for folks (I know there has been some concerns).