search

rwdaigle / miyagi

Miyagi - a Heroku-inspired journal of application development.
http://miyagijournal.com
10 stars 3 forks source link

Switch from Rails to Jekyll or Middleman #4

Closed mattt closed 11 years ago

mattt commented 11 years ago

I actually had quite a bit of trouble getting this installed locally; not being able to run a blog because EventMachine won't compile just strikes me as a red flag.

If the content of this site is to be static, and blog-like, is there any particular reason why this wouldn't be better-suited to static-site generation with Jekyll or Middleman?

FWIW, the most awkward part of writing for DevCenter is shifting from my programmer workflow in text files to the actual Dev Center CMS. Being able to create a submission through a Pull Request feels like a natural workflow.

Thoughts?

rwdaigle commented 11 years ago

I have some thoughts on this mostly based on our experience with the Dev Center. I will expand on them when I have more time tomorrow. Love the feedback and stay tuned.

rwdaigle commented 11 years ago

Mattt, sorry to hear of your troubles getting started with the app. Not sure of the root cause, but that's unacceptable. Let me provide a brain dump of my thinking around the matter of what kind of app stack to use for a content site and you can help @zeke and I find the right balance. 

I have a personal prejudice against two points of relevance here: 1) that GitHub is the right vehicle for managing the content creation, review and overall editorial process and 2) that content should be considered part of an app's source. I'll address in reverse order. 

The current Dev Center app is a monolithic beast and I see the effect such an app can have on a team's progress and ability to implement features. With Miyagi I made a conscious decision to exclude editing and general content management responsibilities from the app. Instead the Miyagi front would merely rendered and display content that was created and edited elsewhere. Just as Miyagi is a conceptual experiment it is also one on where the lines of responsibility should be for the various system components in a publishing app. So, even at a code level, I'd like to keep clear boundaries between the publishing of content and the content itself. 

This is not the same as saying that GitHub, pull requests and all the associated goodies of a programming workflow wouldn't make a good content workflow. However, I have some thoughts here too:

I've found there are two distinct workflows when it comes to the editorial process -- initial draft reviews and incremental edit reviews. There are downsides to using GH for both:

So, the solution I'm going for with these early days of Miyagi is for a simple Rails app that merely fetches Markdown content from a remote source, leaving it up to authors to handle their own writing workflow. I also have visions for a day when Miyagi is much more than just static content, though I suppose looking that far down the road at this stage is just conjecture.

Thoughts?

mattt commented 11 years ago

Thanks for your thorough response. Responding in kind, briefly:

So, even at a code level, I'd like to keep clear boundaries between the publishing of content and the content itself.

Perhaps the content could be included as a submodule inside the code, then. This is a pattern I've successfully used on a couple occasions.

For reviewing initial drafts where ther is a large amount of content to digest it is imperative to be able to comment inline. On GH you can only make inline comments on commits, not on the content itself.

That's not quite true. I can, for instance, leave a comment on individual commit lines.

More than the line or two before/after a change the standard diff view in GH gives you.

I agree with lines not translating as well as code in this view. However, there are two ways around it: either use another diff tool that visualizes it better (a raw .diff will wrap, for instance), or add a script to wrap content to a particular length on commit (my vote for the former).

Co-opting the code editing workflow for written content means taking advantage of powerful tools and processes that we're already used to.

rwdaigle commented 11 years ago

Perhaps the content could be included as a submodule inside the code, then. This is a pattern I've successfully used on a couple occasions.

I have never found submodules to be worth their trouble :( For right now I'd like to keep content separate from the app.

For reviewing initial drafts where ther is a large amount of content to digest it is imperative to be able to comment inline. On GH you can only make inline comments on commits, not on the content itself.

That's not quite true. I can, for instance, leave a comment on individual commit lines.

I don't think I communicated very well. Yes, you can comment on a commit or PR. However, those two things are diff-oriented. Often, as an editor, you want to be able to comment on the content blob directly. For instance, if I wanted to review a draft of the article I just want to go to the markdown of the article and start reading/commenting. Having to open the history view to find the line I want to comment on so I can do so within a commit is a non-starter.

I agree with lines not translating as well as code in this view. However, there are two ways around it: either use another diff tool that visualizes it better (a raw .diff will wrap, for instance), or add a script to wrap content to a particular length on commit (my vote for the former).

Using another diff tool means I'm now outside of GH and am doing a dance between local and remote. It'd be nice to avoid this.

Co-opting the code editing workflow for written content means taking advantage of powerful tools and processes that we're already used to.

I agree. Let's experiment and use a GH repo for individual article(s) for now? All Miyagi (the app, if it stays that way) will need is a URL to a markdown file.

After a few weeks we can re-evaluate. I hope this is satisfactory?

zeke commented 11 years ago

You guys are really good at typing.

a simple Rails app that merely fetches Markdown content from a remote source

I think this approach is fine for now, but it would be nice to have a workflow that let me preview my entry in miyagi as I write it. I personally could stand to leave my $EDITOR behind if the interface was as nice as something like socrates.io. But maybe that's just me. Or maybe I'm kidding myself.

rwdaigle commented 11 years ago

@zeke absolutely! This is where I definitely want to go and would love some help exploring. (It will be no surprise that I think the editing/live-preview tool not be tied to Miyagi in any way). I've added issue #13 for this specifically.

rwdaigle commented 11 years ago

Gents. My attitude was wrong.

The most challenging part of maintaining a content site is content creation and author engagement. While I've said Miyagi should be author-focused being so hesitant to this suggestion made this statement appear to be only lip-service.

Let's see how a static site works.

Miyagi is now Middleman-based. I'll be cleaning it up (updating README, using a middleman buildpack etc...) in the coming days, but the heavy lifting is now done.

Thank you for your suggestion, @mattt - keep them coming!

zeke commented 11 years ago

cc @mattonrails

mattreduce commented 11 years ago

@zeke @rwdaigle I'm excited to hear that Miyagi is now powered by middleman! I hope you find it's a welcome change.

I've been enjoying middleman, middleman-blog and middleman-sync to run my site and blog together purely on S3. It is a workflow I personally enjoy, and I was happy with the performance of the static site, of course.

Thank you for being receptive to this suggestion; it's one I had brought up when I first learned about Miyagi's internals.

Cheers

rwdaigle commented 11 years ago

I love the idea of deploying to S3, though I also like the idea of keeping with my same git push heroku master workflow and having it all just work.

These are fun times we live in.