Redesign coffeescript.org?

[GeoffreyBooth]

Migrating from coffeescript6/discuss#53

Version 2.0.0-alpha1 of CoffeeScript is coming soon, and we’d like to modernize the design of coffeescript.org for the v2 docs. Any designers out there who would like to help with this?

General criteria:

• The content isn’t changing. What you see on coffeescript.org now is the same content we want to present on v2, plus a prominent note about v1 vs v2 which we’ll write soon. If someone wants to add new content, like a tutorial, that would be a separate effort.
• We want to keep it as mostly a single page, so that ctrl/cmd-F quickly finds whatever you’re looking for.
• It must be responsive. We want to keep the left-right side-by-side code examples, which would stack on mobile.
• Since the general design is one long page, I’d like something like Bootstrap’s sidebar nav that has the entire outline and shows you where you are.

Update: The work-in-progress CS2 docs have been merged into 2 branch, and can be viewed here: https://rawgit.com/jashkenas/coffeescript/2/docs/v2/

Please take this as your starting point, and submit pull requests against 2 based on this code. Note that you should only be editing files in documentation; the docs folder is for generated output only (similar to how src compiles into lib).

[jashkenas]

That all sounds perfect.

[GeoffreyBooth]

Some inspiration: https://github.com/PharkMillups/beautiful-docs

[danielbayley]

I'd love to work on this… I wonder if it would be worth splitting coffeescript.org into it's own repo and moving to a CoffeeScript oraganisation?

[jashkenas]

I'd love to work on this… I wonder if it would be worth splitting coffeescript.org into it's own repo and moving to a CoffeeScript oraganisation?

Nope! Changes to the docs are often made in sync with new features being added to the compiler.

[GeoffreyBooth]

What would be screwed up by moving the main repo into the coffeescript organization?

[jashkenas]

What would be screwed up by moving the main repo into the coffeescript organization?

Nothing at all.

[danielbayley]

What about a refresh of the logo/script font to reflect the new modern changes?

[Asc2011]

• pls, make sure to keep the docs on one html-page - so that making a doc-package for Dash/Velocity/Zeal-Docviewer stays as easy as it is today.
• the 'Try Coffeescript'-overlay is still a superb visual-concept for testing little things. I'd like a selector for the CS-compiler-version(s) one wants to use. Maybe one selector per branch 1.xx.x and 2.x.x.
• activate the code-completion, code-coloring of the editor-pane.
• a checkbox if one wants to transp./babelize the CS-output - for the buzz :)
• the right-panel, showing the resulting JS, could get a button to show the AST in the same panel.

Actually i'm working on smth. related.

[GeoffreyBooth]

@Asc2011 The v1 and v2 docs will be separate pages/sites. Our goal is just to teach people how to use CoffeeScript, not how CoffeeScript works; the latter is covered by the wiki of this repo, or sites like https://astexplorer.net.

[Asc2011]

@GeoffreyBooth In the spirit of 'interactive code writing' and 'living documents' i believe its a nice idea to have the docs and a panel to test code side-by-side.
Forget about the AST... which is not on astexplorer.net, too.

[artialex]

Would like to share some thoughts and html mock-up
I really love Laravel website, it always makes me want to learn PHP, so it was my inspiration.
Key points I tried to implement:

• It should be clear at the first glance what is the website about
• Features block, where some important info could be put
• Documentation identical to the old website

So in general what do you think, is that good for start point?
If interested, I took some code examples from here and from atom repo

debug version here : http://codepen.io/lazypacman/pen/yVoQXY

[GeoffreyBooth]

I really like the Laravel docs too. Can we make ours look a bit more like theirs? The pink and brown and yellow feels a bit much to me personally. I suppose if we want to go with the “coffee” theme we should be shades of brown, maybe highlight with dark green . . .

My big request is that we get a scrollspy sidebar like this.

[tyrollins]

Are you looking to have it built with a static site generator - Jekyll, Middleman, etc... - or a specific pre-processor - haml, Sass, Less, jade, etc... - or is basic html / css fine? Additionally, any opinion on libraries such as bootstrap / bourbon, or are we trying to keep it library free as much as possible?

[GeoffreyBooth]

It's just a single page: https://github.com/jashkenas/coffeescript/blob/master/documentation/index.html

There's some preprocessing happening to insert the code blocks, but that's it. I'd prefer not to add a CSS preprocessor into the mix unless our styling gets much more complicated than it is now. Our target browsers for CS2 are evergreen.

I was thinking of adding the Bootstrap JS at least, to enable the scrollspy; adding its CSS too would be fine I think. I would load both via CDN.

[GeoffreyBooth]

@jashkenas @lydell I’ve been working on the foundation for the v2 docs in the 2-docs branch. Demo here. I’m far from finished, but this is a first draft.

I haven’t done any significant styling yet, in the hope that this thread will produce a design we all like. The styles for now are plain Bootstrap 4 and default CodeMirror syntax highlighting. What I’ve been focusing on is implementing a better build process, a scrollspy sidebar, and editable code examples. Try editing any of the CoffeeScript code blocks!

The content is still the same from v1, aside from the JavaScript output from the v2 compiler, so that still needs to get updated too. But this page is the skeleton of what the v2 docs will be. Anyone else on this thread, what would you do to this page to make it better?

[lydell]

@GeoffreyBooth Very nice first draft! I like the sidebar and the editable code examples very much. 👍

[tyrollins]

@GeoffreyBooth The editable code examples are awesome, very nice addition!

I hope to have a small demo or two together this weekend and was curious your thoughts on a collapsable sidebar (toggle offscreen by clicking menu button or similar)? I am by no means a designer, but hopefully I can provide something of use, if even only a snippet here and there.

I will update in a couple days (Monday the latest) with what I have. Thank you for encouraging contributions.

Cheers.

[GeoffreyBooth]

My thinking was to have a collapsible sidebar on mobile.

[GeoffreyBooth]

Second draft. This makes the sidebar work on mobile. Sorry if I stole your thunder @tyrollins, I was already working on this.

I think I’m going to focus next on the actual content of the sidebar, shortening some of these heading titles and otherwise editing the text. The other big technical thing to figure out is “Try CoffeeScript” (should we call it something else? Online Demo?) which is basically just a fullscreen version of the editable code blocks.

What I could really use help on is some vision of how these pieces should look. Fonts, colors, margins, padding, etc.

[spro]

A bit of padding to boost (read/scan)ability:

p, .code-example {
    margin-bottom: 1.3rem;
}

h2 {
    padding-top: 2rem;
    margin-bottom: 1.3rem;
}

h3 {
    padding-top: 1rem;
}

[connec]

I feel that the code blocks (and perhaps the menu?) could use a bit of line spacing.

.sidebar {
  line-height: 2;
}

.CodeMirror {
  line-height: 1.25;
}

Less trivially, I wonder if there's something more that could be done to evoke the original site? Perhaps we could keep a floating header in a more material design style?

Also, I'd love there to be a more prominent link to the GitHub repo. For years whenever I've typed "coffee" into Chrome it only recommends the coffeescript.org address, and the link to the GitHub repo is pretty awkward to get to (Table of Contents -> Resources -> Source Code).

[carlsmith]

I've been unable to do much lately (health issues), but just wanted to chip in to say that the old site had a nice look that people associate with CS. Probably best to rip that off as a starting point.

Also wanted to say a big thank you. So nice to know Coffee's future is bright.

[GeoffreyBooth]

Thanks @carlsmith. It was @jashkenas who requested that we move away from the “brushed metal” aesthetic; maybe it can be modernized in some way?

@connec take a look at the site on mobile (or in a narrow desktop browser) and you’ll see a header bar. Perhaps that should be present on all sizes? And on the larger breakpoints, it can have a few important links up there.

[danielbayley]

@GeoffreyBooth

Are you keeping this on your personal fork, or pushing to a branch of this repo?

What I could really use help on is some vision of how these pieces should look. Fonts, colors, margins, padding, etc.

Some thoughts I had…

• Definitely more overall whitespace.
• I think on mobile (viewed on an iPhone 5S admittedly…) when the sidebar is expanded it should take up 100% width then maybe auto-collapse when a selection is made
• Agreed on having a fixed floating header at all sizes with a few of the most important links (like GitHub as @connec says
• A nice minimal complimentary colour palette with coffee/brown as the primary
• Possible slightly more modern update to the logo and script font used to reflect that "CoffeeScript is back"!

[carlsmith]

Thanks @carlsmith. It was @jashkenas who requested that we move away from the “brushed metal” aesthetic; maybe it can be modernized in some way?

Ah, fair enough. Sorry. Haven't really followed this. I still like that look, but yeah, it's not very modern.

A nice minimal complimentary colour palette with coffee/brown as the primary

Yeah, a modern, flat, minimal look, with two or three different shades of a nice mocha to add some colour and fun, sounds pretty nice, but I'll leave it to you guys. Too many cooks.

All the best.

[GeoffreyBooth]

Okay, I’ve taken a stab at some colors and fonts and updated spacing. I’ve also started reworking the header and sidebar, which I hope should be working now on desktop, tablet portrait and mobile.

I’ve also started rewriting the text. There’s now a section explaining what CoffeeScript 2 is (what else should I say or not say?) and I’ve removed several paragraphs of outdated info. I was surprised to notice that some very basic parts of the language never had proper explanation—we have a section on block strings and block comments, but there’s no section on simple strings or comments. I’ve added those, please let me know what you think. I put them in as isolated commits, so that we can backport these additions to the v1 docs if people want.

Still to do:

• Try CoffeeScript
• Improve the syntax highlighting somehow? Now that the code examples are editable, they’re using CodeMirror, which has inferior syntax highlighting to Highlight.js which we’re using for the code examples in the v1 docs. Does anyone know how to use Highlight.js with CodeMirror, or does someone want to patch CodeMirror’s CoffeeScript syntax highlighting to better support our newer keywords and things like backticks/triple backticks?

Pull requests against my 2-docs branch are most welcome!

[connec]

I think it looks really good, nice work!

[jashkenas]

Lovely stuff, @GeoffreyBooth — it's coming along great!

I might find time to muck around in your branch a little bit in the next few weeks. But my only real constructive criticism right now that might be easy to tweak ... is to echo @connec and @carlsmith's comments from above.

The new layout is lovely, but it could be nice to maintain a little visual consistency from the old site, to make it feel like home: just a bit of color scheme, and maybe a very faint ribbed background on part of the page could do the trick. No brushed metal required.

[GeoffreyBooth]

Okay, I’ve added some ribbing. If anyone has more specific ideas about how to evoke the old site, please suggest some code 😄

Any thoughts about CodeMirror and syntax highlighting?

[jashkenas]

Only thought is that — I think getting a pull request in to Codemirror / upgrading their syntax highlighting is the way to go.

[GeoffreyBooth]

Okay, I’ve added Try CoffeeScript, including its “play” and “link” buttons. Still to do (pull requests welcome!):

• Improve the CodeMirror syntax highlighting. Per @jashkenas, this is probably best done by submitting a PR against CodeMirror. That would have the added benefit of improving CoffeeScript syntax highlighting across the web, e.g. at jsfiddle and other places.
• Update the text about classes to reflect [CS2] Compile class constructors to ES2015 classes #4354.
• Add a section about upgrading from 1.x? Or just link to the wiki page from the “CoffeeScript 2” section?

[jashkenas]

Having a section about upgrading from 1.x in the 2.0 docs makes sense to me.

[mrmowgli]

Wow! Great work so far Geoffrey Booth! My only real comment is that the transition from the examples to the CoffeeScript 2 section was that it left me wondering "What is CoffeeScript 1? Do I need that? What's the difference?"

I tried it from my Samsung Galaxy, and it formatted quite nicely. I did run into an issue where the back button ruined the formatting. Other than that everything looks amazing! Very excited to see all of this coming together!

[xthezealot]

Good job @GeoffreyBooth!
I only have some restraint concerning:

• The top bar which should be less reddish.
• The main font size which is unnecessarily big. Lato 300 is also too thin under ~36px IMHO.
• The use of green color which reminds me of MongoDB and makes CS too related to Node.js.
• The code color scheme which could be more "fresh" and neutral at the same time.
  DuoTone Dark Earth could be inspirational here.
• The dark backgrounds for the code which create big visual divisions and breaks the reading flow.
  There could rather be a clearer separation between the CS source part and the compiled JS part.
• The light stripes on colored backgrounds which are "old-fashioned" IMHO.

Otherwise, I quickly designed my own interpretation (if you want to go with that and need code contributions, let me know):

[GeoffreyBooth]

@ArthurWhite sure, do you want to submit a pull request? You could show everyone your version via rawgit.com like I have.

Please make sure it works on mobile and tablet. That was the reason I added the top bar, though it could perhaps only be visible on tablet portrait and down. The light stripes are definitely retro, but they were a request from the crowd (see above on this thread). I would say go ahead and replace them, but don’t be surprised if people ask for them back 😄

[xthezealot]

I don't have an HTML version for now, only this preview made in Sketch. 👨‍🎨
But if and when everyone will reach consensus over this redesign "issue", sure, I'll be happy to do some pull requests.

(The responsiveness should not be a big deal, even without a top bar.)

[GeoffreyBooth]

I’ve merged the CS2 docs as they are so far into the 2 branch, so we now have a better work-in-progress URL: https://rawgit.com/jashkenas/coffeescript/2/docs/v2/

At this point, I think further revisions (or redesigns) should take what’s on 2 as a starting point, and pull requests should be submitted against that.

[tyrollins]

@GeoffreyBooth great job! Is there a particular deadline that you have on the docs design, or is it just the sooner the better? I'm not aware of the time frame for CS2 completion, so not sure how to gauge it... But I'm eager to contribute.

[GeoffreyBooth]

@tyrollins I’m eager to get the first alpha released whenever #4424 is finished, which hopefully isn’t too far away. You can see our progress at https://github.com/coffeescript6/discuss#coffeescript-2.

The alpha can always launch with the docs as they appear now and we can revise them.

[GeoffreyBooth]

No point in keeping this issue open, though that’s not to say we’re uninterested in improvements to the website, or even further redesign. Feel free to continue to post mock-ups for feedback, but at this point if you want to see your mock-up realized you need to do the coding yourself and submit a pull request with your new design. Thanks!

[GeoffreyBooth]

Flattery:

Introducing Docup 1.0, the single-page documentation generator for your open source projects (no build step, just a 30KB JavaScript file)

🧙‍♀️ https://docup.now.sh

– @egoist via https://twitter.com/_egoistlily/status/1261673949097627648?s=20

[egoist]

@GeoffreyBooth I was waiting for someone to point this out, thank you. Will add a link on the website to address the inspiration.