Prototype to Production, Part 1: Prototype Preparation (cleanup)

[smichel17]

Background

While we’ve made progress in other areas, feature development on https://snowdrift.coop itself has been stagnant since late 2016, when we ran out of funding for @chreekat to work on it full-time. Instead, it continued on a prototype, which was easier (read: possible) for our designers to work with. This avoided one roadblock but created another: the prototype rapidly became out of sync with the live site, making it harder to integrate any improvements.

A month ago, I decided to take on the challenge of repairing our development pipeline. First, I had to understand the problems with the current state. The very short version is:

• The main issue with frontend development is long compile times. When your reference is a mockup, frontend work involves a lot of visually checking to make sure that things look right. Waiting 10 to 60 (!) seconds to see the result of a property change is not workable.

• A secondary issue is lack of Haskell devs to support frontend folks who may not have experience in Haskell.

• A minor issue is that, from a prior attempt to bring the production site up to date with the prototype, there are a mix of styles in production.

Second, I had to come up with a plan^[1]…

Goals and non-goals

• We don’t want to throw away the work on the prototype, so we need a process for porting that work back to the production site.

  • We would like to avoid making the mix of styles on the production site too incoherent during this transition process.

• Once the production site is up to date with the prototype, we need a workflow for frontend development that makes it all the way to in production, so we don’t get stuck, unable to update the live site, again.

  • We don’t need this workflow to be perfect, or even very good. It just needs to be good enough that we’ll actually use it, and can iterate from there.

Plan

Long compile times affect building new pages and making any modifications larger than phrasing tweaks, but should not affect importing a new page from the prototype by copying it wholesale:

• Both sites use sass, so it can be copied verbatim.
• The prototype (a static site generated with piecrust) uses html with jinja templating, while the live site uses yesod’s hamlet. Html can be automatically converted to hamlet, but the splices will need to be done by hand.

That’s some work, but not too much. Most importantly, because the sass is identical, the site should look right the first time it compiles; it’s not the ideal workflow, but hopefully it’ll be good enough to satisfy the goals.

Note: The sass is split between styles for individual pages and shared styles (“main”), which are included on each page via sass imports. In the production site, these shared styles live in the same directory as the page templates (navbar, footer, etc); we’ve been calling this combination a “skin” for the site.

There are currently two skins, main-v1 and main-v2.

So

1. Update the prototype to be production-quality.
   • It was built by the volunteers who had time on their hands, not necessarily coding expertise. As a result, it is functional, but not particularly maintainable.
   • I don’t want to spend effort porting the prototype work to production, when I know it’ll have to be re-done shortly after.
   • This mostly involves reducing the amount of margins + padding to position individual elements, which create non-obvious couplings and make layout adjustments very time-consuming.
2. Import the prototype pages that are ready to production.
   • Create a new skin on the production site, imported from the current prototype. ex: main-v3.
   • For each page to be updated, replace the current production version (hamlet and sass) with the version from the prototype.
     • Note: The sass @import paths will need to be updated to main-v3 instead of main, as they are called on the prototype.
   • For each other page, swap it to use the new skin’s templates. This way, all pages will have a consistent header, footer, and metadata (the latest version), even if the content itself has a mix of styles.
3. To make changes in the future, update the relevant page in the prototype, then import it to production using the same process.
   • The downside of this approach is that it will involve repeatedly converting more-or-less the same html to hamlet; the viability of this plan rests on the assumption of a fairly painless conversion process (or at least, less painful than the current workflow).
4. Remove old skins from production once there are no longer any pages using them.

When all pages in production are up to date with their prototype equivalents (which implies only one skin left), then the plan is complete, and it’s time to start working on improvements to the main site’s frontend workflow, so we can remove the crutch of the prototype and develop on the production code base directly.

---

1. I’ve been saying the forum is a good place to follow development, so I figure I ought to make good on that. ↩︎

[wolftune]

@smichel17

frontend work involves a lot of visually checking to make sure that things look right. Waiting 10 to 60 (!) seconds to see the result of a property change is not workable.

When I was hacking on CSS years ago in similar cases, I always just did these tweaks in Firebug right in my browser. When I figured out the correct look, then I changed it in the actual code and verified.

At the time, I recall seeing distinct CSS files in the rendered site so that I was able to often get close to the right level in the cascading. I wasn’t limited to in-line hacking on exact items.

Surely that approach is still feasible using browser dev tools (though Firebug is gone, it was integrated into Firefox). So, doesn’t that just solve this “main issue” for at least the majority of the time?

Of course, quick compiling is preferable, but is it really a blocker?

[Adroit]

@wolftune

I always just did these tweaks […] right in my browser. When I figured out the correct look, then I changed it in the actual code

That’s exactly what I said earlier this year - the answer is “not quite, because we don’t use CSS, we use Sass”.
(And while it’s of course possible to paste CSS into Sass, they understandably want things to be sassy - mixins and all. Which means you’re back to waiting for the recompile step.)

But yeah, I do a lot of web design work this same way. Tweak it live, in-browser (dev tools) till it looks good, then copy that result to the real thing in the right place. Unfortunately, with the Sass setup, that “right place” is lots of different places, and once you split it up you also have to make some substitutions. (I actually learned Sass just to help out with this, but it turns out that knowing Sass doesn’t change the hard part I described…)

[smichel17]

(Thought I’d replied to this)

@Adroit basically hit the nail on the head, although I would argue it applies to some (lesser) extent regardless of preprocessing. It’s fine enough for small changes, but if I have to change ten properties on four different classes, it becomes hard to keep track of what I’ve changed. I guess with plain css you could copy the entire stylesheet, but when I’m experimenting I don’t necessarily always put styles on the “right” classes (and sometimes just directly on the element, which can’t be copied).

[wolftune]

That makes sense. Thanks for clarifying. So, determining what styles will achieve a design is doable with browser tools, but that doesn’t answer the question of where in the Sass to put the styles. Right?

[Adroit]

@smichel17

when I’m experimenting I don’t necessarily always put styles on the “right” classes

…but you can! And in doing so, you will not just be “experimenting”, you will be doing proper designing/coding – all with instant visual feedback, which is what we’re wishing for.

(So, hate to say it, but the preprocessor is the blocker.)

@smichel17

if I have to change ten properties on four different classes, it becomes hard to keep track of what I’ve changed

[smichel17]

TIL there is a changes tab