Documentation Revamp

[chriseppstein]

Evidently. A bunch of people want to help revamp the docs.

If you're one of them, start talking about it here. We'll use this issue as a mailing list of sorts.

[timhettler]

/wave

Perhaps a decent place to start is for people to point out any framework documentation they like, so we can explore where the Compass docs can be improved. I'll do some research over the next couple of days.

[jina]

Word. Today I pointed out that contrasted() existed — they had no idea it existed and posted their own color contrast mixin today. But they knew about lightness? Some short but clear articles like "Color & Theming with Compass" might be helpful. It can show practical applications of the mixins and functions with examples. I can help with this one in particular.

[keithort]

Here is a quick rundown of some ideas that I came up with

Switch to tabs so the page is much shorter while showing the available information quickly. Intro Examples | Imports | Configurable Variables | Mixins

Move scss/sass buttons next to mixin's section. seem hidden for one. or possibly ditch them and on the mixins section, giving the option to view source as SASS or SCSS.

Interactive documentation (experiment with the mixins showing realtime output of he rendered css and the styles). This basically is to take the current examples and bring them to life.

[keithort]

Also minor clarification, on http://compass-style.org/reference/compass/css3/images/, for the filter-gradient mixin, there is no mention of the need to pass RGBa values in leading to hours of frustration on my part.

[JohnRiv]

The documentation is great (much more in detail than most open source projects). The only issue is I sometimes have trouble finding what I need quickly, so I usually just use Google or the Search the docs.

For me, the best improvement would be if http://compass-style.org/reference/compass/ listed everything in that section on that page & then those would deep-link to a page with more details. For example if I want to look up "inline-list", instead of having to guess if that is under Helpers, Layout, Typography or Utilities, it'd be easier to just hit command+F and find it in the page.

Also while we're at it, if we can provide usage examples for the mixins that don't yet have examples, that'd be useful. For example, last week I wanted to use headings() and I couldn't remember exactly how to use it & the docs don't provide an example.

[Snugug]

I think a little update to the IA would help greatly. The actual documentation of the functions and mixins are great, it's getting around the site and discoverability that's the thorn for me. For instance, if I click lists from compass/utilities, I'm taken to compass/typography/lists. Now that may be where the partial lives in the Compass framework, but it doesn't make a lot of sense to me as a user navigating the site.

Little things I'd like to see: removing comments, a responsive site, and a more consistent UI (the header/layout jumps from contained to full width depending on the section).

[cimmanon]

I would like to see a stronger emphasis on the extension aspect of Compass. To someone not familiar with Compass, there appears to be little difference between Compass and Bourbon: both provide a bunch of least common denominator mixins (css3 prefixes, etc.). It's good that Compass comes with a base library, but most people assume that's all there is to it.

It would also be nice if it were easier to find extensions, rather than everyone reinventing the wheel all the time. The tutorial on extensions could use some fixing up to make it easier to understand. It is currently hidden under "Get Involved". Maybe Compass should have a template for creating a new extension as well.

[chriseppstein]

@keithort @Snugug The small issues you guys mentioned (lists link, filter-gradient) just sound like bugs to me. Can you file them?

@cimmanon A new project was kicked off at SassConf to build an extension registry. https://github.com/sass/sass-registry. I would like to combine efforts with them.

Responsiveness: I only want to tackle this during a redesign. Only 5% of visits are not desktop and it's a lot of work. I know it's a point of pride in "Doing it the right way" but I don't want perfection to be the enemy of making solid improvements in the near term.

Comments: have already been removed on master.

it'd be easier to just hit command+F and find it in the page.

We have a site search feature. it works pretty well. Also: this site rocks the SEO. you can pretty much google compass <anything> and end up where you need to be.

I'd like to know if there's a short term project over the next couple of weeks where we rework the IA and add a few new pages of critical documentation, throw in some more examples. And launch a better site with the upcoming release.

Then, if someone wants to spend a few months to lead a redesign, I'm ok with it.

I agree that the messaging about what compass is and how it fits into the sass community at large needs work. Can this mostly be accomplished by reworking the homepage?

[micahgodbolt]

putting my name in the hat

[jathayde]

I'm game to help wherever I can

[chriseppstein]

There's some open documentation issues:

• https://github.com/chriseppstein/compass/issues?labels=documentation&page=1&state=open

And it would be great if we can tag any other issues with the documentation label.

[chriseppstein]

There's a guide for how to contribute docs:

https://github.com/chriseppstein/compass/blob/master/doc-src/README.markdown

But no one seems to know it exists. So I guess we should fix that.

[chriseppstein]

I've got a push to the docs happening in the next few hours that makes it all place nicely with the latest releases.

[chriseppstein]

Also: you guys are awesome.

[mirisuzanne]

+1 for awesome you-guys.

[keithort]

@chriseppstein oh the humanity of the grammer faux paw (and the bad pun).

[jina]

omg. I'm dying over here. faux paw? that is the best.

Jina Bolton Sent with Sparrow (http://www.sparrowmailapp.com/?sig)

On Wednesday, October 16, 2013 at 10:36 AM, Keith Ort wrote:

@chriseppstein (https://github.com/chriseppstein) oh the humanity of the grammer faux paw (and the bad pun).

— Reply to this email directly or view it on GitHub (https://github.com/chriseppstein/compass/issues/1413#issuecomment-26440295).

[chriseppstein]

A suggestion from @jlong: Rename "Help" to "Get started" and move it before "Reference".

[opinxit]

I admit: I'm one of those people who is totally guilty of bashing the compass docs on Twitter in the past. Here are some notes for some of the issues I've had them (possibly even just the first time I used them). I realize the docs have been steadily improved over time, that they are better now than than were.

So when i go to http://compass-style.org/reference/compass/,

1) I'm told: @import "compass", but it's a little unclear what's added and what's not. (one headline is a verb; the other, not so much). Perhaps reiterating the file structure rather than just listing the conceptual rubrics..? In other words, what exactly should I expect to see in a stylesheet that includes: @import "compass".

2) I'll second the IA issues mentioned above by @keithort @Snugug.

3) after i've drilled down, maybe i'm no longer aware that compass/css3 is included automatically if i've already included compass..? versus those that do need to be included explicitly

4) In the main nav -- shouldn't install come before reference?

I really like the view source links and links to github (I don't remember seeing those back in the day--maybe I missed them).

Lastly, I would like to contribute; I tried to get the docs working locally, but was stymied by a rb-fsevent 0.4.0 gem install issue that I've yet to resolve.

[timhettler]

When I first started using Compass it wasn't immediately clear that I was supposed to use a different command to compile. (compass vs sass)

I think the entire install & get started flow needs more hand-holding.

[chriseppstein]

FYI: i did some reorg of the nav on the beta site: http://beta.compass-style.org/

let me know what you think

[jina]

:+1: I dig it. I think it's a good move to have the help docs with articles before the code reference, which is more like a glossary. For the Install page, may I suggest moving the "hate the command line?" section up into a second column so it's not missed at a glance?

[nemoDreamer]

Folks, the docs are great, but a recent folder structure change has broken All The Things. I appended some "dead link" issues here: #1981 (found this post too late).

Is http://compass-styles.org a public repo? Can we create pull-requests for a quick fix?