CS2 Discussion: Project: Redesign coffeescript.org?

[GeoffreyBooth]

I’ve been talking with @jashkenas about how to manage the hosting for the documentation for CoffeeScript 2, and per jashkenas/coffeescript#4360 we figured out how to host both the 1.x and 2 docs from the same repo. Anyway in the middle of this discussion, Jeremy suggested that coffeescript.org was overdue for a design refresh. Any designers out there who would like to redesign coffeescript.org for v2?

[YamiOdymel]

I just drew a layout for suggestion, I think that we should have a landing page instead of a documentation homepage.

[GeoffreyBooth]

@YamiOdymel What would be on this landing page?

The current documentation has the following sections:

• introduction
• language reference
• compiler reference (i.e. the coffee command)
• general reference (related projects etc.)
• “Try CoffeeScript”
• annotated source

Currently the first four are on one page, and the latter two are pages of their own. But that can change; I think the compiler reference could get its own page, along with info about how to use CoffeeScript with Browserify and the like. The general reference could likewise be buried a bit.

One idea I had was to make every code block a “try” block; all the examples could become interactive.

[YamiOdymel]

@GeoffreyBooth

The sections on the landing page are:

• Slogan + call to action
• Syntax overview
• Features
• Links or core members

and sorry, what do you mean by the "current documentation"? The old CoffeeScript page? I think the references can be separate from the homepage so we won't put too many things in a single page.

Since I'm not a native English speak, I might missed some of your point, I'm sorry :(

Landing page

Slogan, Call to action, Syntax Overview

Features

Links

Or can be core members :D

Compiler reference page

Tutorial, Documentation page

It's a little bit like Laravel Docs but with the interactive example blocks.

and the left sidebar is the index of the documentations.

---

Icon source: Document by useiconic.com from the Noun Project
Icon source: code by Curve from the Noun Project

[GeoffreyBooth]

@YamiOdymel This looks pretty good. The content we have is the content currently on coffeescript.org; so there’s no tutorial, for example. Maybe we should add one, but let’s design for the content we currently have, and worry about future content after it’s written. We also don’t need a section for core members.

Can you make an HTML mockup for this?

[YamiOdymel]

@GeoffreyBooth Sure.

Landing page

Docs

The code block can only be vertically (because the screen is not wide enough), or maybe we should remove the left sidebar (the indexes), but I have no idea where should the indexes go.

References

[GeoffreyBooth]

I think we need the code examples to be side-by-side. It’s hard to follow the equivalence if they’re stacked. Let’s just use responsive design and stack only when necessary.

As for the sidebar, what about something like what Bootstrap uses for their sidebar nav?

I think the homepage of the future site is the current coffeescript.org intro text and “Overview” section, including the long side-by-side code block. Basically from the top through (but excluding) “Installation”.

Here’s how I would break up the current content into pages:

• Home
  • Intro
  • Overview example
  • links/CTAs to other key pages like Try CoffeeScript, Installation, etc.
• Try CoffeeScript
• Download and Use
  • Installation
  • Usage
  • Source Maps
• Language Reference
  • Functions
  • Objects and Arrays
  • etc.
  • Literate CoffeeScript
  • Cake, and Cakefiles
  • “text/coffeescript” Script Tags
• Learn More
  • Books
  • Screencasts
  • Examples (first link should be to the annotated source)
  • Resources
  • Web Chat (IRC)
  • Change Log

[jashkenas]

Apologies in advance — but to throw my two cents in the ring:

• This ticket should be over on the coffeescript repo — where all of the watchers can see it and chime in.

• Let's not turn CoffeeScript.org into a generic "Yet Another JavaScript Open Source Project" page. A little freshening up of the style would be great — making it look like every other project out there doesn't seem wise.

• Keeping all of the docs on a single page is a feature, not a bug. It means you can quickly go to coffeescript.org and CMD-F search for literally anything you might need.

• What would really be lovely is a nice responsive-ization of the homepage, a style cleanup (CoffeeScript.org dates from the bad old days of brushed metal), and perhaps an exciting new near-top section explaining the vision for V2. A lot less work than trying to redo the whole enchilada in the style of everything else...

[YamiOdymel]

A little freshening up of the style would be great — making it look like eve..

Sure.

[GeoffreyBooth]

Closing in favor of jashkenas/coffeescript#4370

[coffeescriptbot]

Migrated to jashkenas/coffeescript#4947