[site] Site-map & Content

[corysimmons]

We can get a list of docs from @kizu 's post here: https://github.com/LearnBoost/stylus/issues/1242#issue-23228764

We need to consolidate all this to one folder in one branch. I disagree with @kizu here. I'd prefer they be put in the gh-pages branch as I don't see a reason to clutter core Stylus with docs. Is there a technical reason behind it?

Anyway, let's start a chat about what content is actually going to go on the site.

[corysimmons]

We have a nice/fast inline editor: http://learnboost.github.io/stylus/try.html

I'd love to take this away from being a step-by-step tutorial and just use it to provide http://learnboost.github.io/stylus/convert as a stylus2css converter that works both ways. People use these services all the time, http://js2coffee.org/ is a great example.

I'd also like to implement small inline editors all over the place. So we teach people a concept, and then provide a small/editable example right there next to the piece of doc that teaches the concept. I do this on http://jeet.gs and it's okay, but CodePen is laggy and the editor isn't necessarily beautiful. However, we could customize our editor however we wanted. Maybe even add a button next to a block of doc that would accordion down an inline editor? Just hide it by default.

I've also found that people like video tutorials so maybe this could be a little button beside each doc block that expanded a modal tutorial about a concept. I'd be willing to do these mini-tuts and maintain them.

@thefoxis - Thoughts? Also, I'm drawing a blank for the homepage. I'm not sure what I want the user to immediately see.

[kizu]

I don't see a reason to clutter core Stylus with docs. Is there a technical reason behind it?

Ok, here is what I think: the docs for the actual code, describing how things work, which bifs we have etc, should be placed near the code, and everything else (tutorials, articles, style guides etc.) could go straight into gh-pages branch. The docs that describe the actual code need to be near the code because they should be linked together. When someone is doing a new feature, it is really much easier to write docs alongside, in the same branch. This way, when the feature would be merged into master, the docs would be merged too. Each branch, each tag, each git revision would have actual docs for the stuff there is. If we'd write all those docs in gh-pages, we would need either to postpone the updating docs until the code is merged or to create extra branches just for docs, all to ensure the docs are up to date and don't have things that are yet not released.

That is similar to the code testing — it is much more sane to keep the tests in the same branch as the code.

About inline editor — I thought we should just make all example live-editable :) We should load docs pages with pre-rendered Stylus and CSS before-after code, then lazyload the inline editor (as it is not that small), then enhance all the examples with the ability to change the source. This way you could take any example and edit it as you'd like :) Of course, there should be a “revert to an original example” button or something like that.

[thefoxis]

:thumbsup: for inline editor, it's great to be able to try stuff in the browser, not copy paste to the editor. Way less hassle.

Proposed sitemap:

1. Landing Page
   • Current release information
   • Link to Github
   • How to install (? if not a separate page)
   • Getting Started / Documentation — an important division between people who are pros and people who want to learn. We could include some materials for developers who are starting with preprocessors.
   • Several paragraphs describing what's Stylus and how it's different/better from other preprocessors, how it's the thing for Node environments
   • Short blobs on community and contributing
2. Style guide (visual and code for contributions) + Branding
3. Documentation
4. Contributing
5. Community (optional — resources about Stylus, conference talks, etc.)
6. Install (optionally separate, Sass has a really nice guide for compiling through apps, command line, etc.)

How does that sound?

[corysimmons]

1. Landing Page
   • Current release information :heavy_check_mark:
   • Link to Github :heavy_check_mark:
   • How to install (? if not a separate page) :heavy_check_mark:
   • Getting Started / Documentation — an important division between people who are pros and people who want to learn :question: (can you provide an example?) . We could include some materials for developers who are starting with preprocessors. :heavy_check_mark:
   • Several paragraphs describing what's Stylus and how it's different/better from other preprocessors, how it's the thing for Node environments :heavy_check_mark: (Although I don't want to get too caught up in a mud slinging fight)
   • Short blobs on community and contributing :heavy_check_mark:
2. Style guide (visual and code for contributions) + Branding :heavy_check_mark: (Should this be within Documentation?)
3. Documentation :heavy_check_mark:
4. Contributing :heavy_check_mark:
5. Community (optional — resources about Stylus, conference talks, etc.) :heavy_check_mark: (I want to see popular Stylus npm packages, and players in the Stylus community under this, but maybe we should move conference talks and learning resources under a subpage of Docs?)
6. Install (optionally separate, Sass has a really nice guide for compiling through apps, command line, etc.) :heavy_check_mark: (We should have a really quick/easy install on the frontpage and rename this section "Integration")

[thefoxis]

1. Division between users starting with Stylus and professionals — professionals look for a reference (documentation) and beginners would possibly like to know what a preprocessor is, how does it differ from regular CSS, how they can compile it to CSS (there are so many ways), maybe see some introductory examples. That might be presented as docs themselves, if the copy is improved. Right now parts of the Stylus documentation are kind of JS/back-end developer oriented, at least that's how it reads to me (you need to understand hashes, functions, etc. — and for some front-end developers this is black magic). Sass has guide which I think portrays what I mean.
2. Node — yes, I don't want to get into Ruby vs. Node fights etc. We might mention or not. It's just about a quick intro to Stylus in general and use cases.
3. Style guide — on Sass website it's a separate thing. I don't think it belongs to docs. Documentation describes how stylus works, not how the website looks (patterns, layout elements, typography).
4. Community — good idea with npm packages! Also Nib and similar "frameworks". Learning resources might be moved to getting started or docs, true. So then community would be frameworks, modules, activity on Stylus itself (maybe?), new contributors, stuff like that. Maybe stats on the activity of the repo too. For inspiration see Engine Yard's community page.
5. Integration — yep, that works, section on the main page.

[corysimmons]

:+1: Sounds good. Are you working on the UI then?

[thefoxis]

Yep, first I'll have a look at fonts and colors. Will upload propositions for those soon, in separate issues :)

[corysimmons]

Sounds good, thanks @thefoxis

[corysimmons]

@thefoxis Update? If you haven't had time to start, we can help.

[thefoxis]

@corysimmons — I'll get on it this week, I just have a full-time job at &yet, so sometimes I can't contribute daily :) But getting on it. No worries.

[corysimmons]

@thefoxis np, I completely get that and don't mean to rush you. Excited to see what you come up with! :D

[mordecai174]

I am going to take a stab at the design too, if no one objects?

I'll be putting time in on Friday for this. We can look over the designs and see what is working, and what isn't etc.

Excited to be able to help out on this!

[corysimmons]

:+1:

[thefoxis]

@mrossimojo sure, we can collaborate and merge the best elements. Can you work in LV too?

[mordecai174]

@thefoxis I can do whatever we want to do. I'd rather not mix & match designs, but we can review and discuss what we like/dislike and evolve each, or go one specific direction. Sound good?

[thefoxis]

I wanted to start with colors + typography and then do the actual comps. I didn't wanted to do mixing and matching, but more like picking good ideas and then applying them.

[corysimmons]

@thefoxis Have any colors/typography mocks yet? I'd love to see. :)

[mordecai174]

@thefoxis just go for it. I think we have the page hierarchy, and content, so maybe just do your version of a page design, and I'll do the same.

[corysimmons]

@kizu For our work on this, can we put a small company logo in the footer? If so we can devote more resources to this and churn out something gorgeous/amazing quickly.

[corysimmons]

@visionmedia would this be okay with you?

[tj]

depends how it's presented I suppose, but there's quite a few people/companies that have contributed so maybe something like "brought to you by / / "

[thefoxis]

I think the idea of having supporters is nice, especially that it can draw more attention and we could even consider setting a Gittip account for Stylus/Jade so all the core contributors can get tips for fancy :coffee:

Or something like that.

Also it promotes the project anyway.

[corysimmons]

@visionmedia Just something small and in the footer like "Website built by MojoTech" (with our logo small). Maybe we can include big contributors of Stylus on the Community page?

@thefoxis Panya does like fancy :coffee: =)

[corysimmons]

@thefoxis http://dribbble.com/shots/1462256-Stylus-Redesign coding this up this evening. After that we can add sections and such and launch.

[corysimmons]

@kizu I'll probably need some help integrating the Tenkan stuff.

[kizu]

Feel free to ask any questions!

Regarding the provided design. Right now it looks almost like a skin for the existent Stylus' site, I'm not sure we need to do any actual coding before we're finished with the whole site map, features set etc.

[corysimmons]

@kizu It is very similar, but it will be clean/responsive/retina-friendly so those shouldn't be understated.

Why don't we get these changes in, then we can focus on adding additional pages and perhaps restructuring it a bit to be more inline with what @thefoxis came up with. I'll provide reusable styles so anyone can add whatever they want, wherever, whenever. =)

[tj]

hmmm I'm not a huge fan, I'm sort of in the middle one it, don't hate it or anything but not in love with it (as far as putting the effort in to redo everything)

[corysimmons]

@visionmedia Like this one better? https://www.dropbox.com/s/asznfre6klqnnts/stylus.m4v

[corysimmons]

@visionmedia Also, care to be a bit more specific with your critique so we can fix it? =)

[tj]

Definitely better than what we have now. I'm bad at explaining design stuff haha. I like bland but it's the wrong kind of bland (for my tastes at least). I'll see if I can maybe mock something up later, do we have vectors of the logo?

[corysimmons]

@visionmedia Yup https://github.com/mojotech/stylus-redesign/tree/master/branding

Could you try to mockup quickly? I can code it up today after work (in about an hour).

[mordecai174]

Sorry it isn't what you were hoping for, I cannot waste any more time on this project though unless there are minor changes you'd like to see. Best of luck.

[kizu]

@corysimmons

Why don't we get these changes in, then we can focus on adding additional pages and perhaps restructuring it a bit

All I'm saying is that the whole layout could change, the whole conception could change, the whole site structure could change. This would lead to another radical change to the design, so implementing one design now and then implementing another one once again would be a strange decision.

Yes, it is possible, and the current site could be easily restyled, but I'm not sure we need to restyle anything, as what we have now works (not ideal, but).

Implementing anything new now would limit our possibilities, as any changes should be in par with what we've implemented.

@mrossimojo thanks for the work you've done already!

[corysimmons]

@kizu Yeah, now that I think about it, it would be kinda weird.

[tj]

FWIW it's not really up to me haha :D It's nicer than what I did, but I agree with @kizu that it's not a huge departure from the setup we have now, I'm also terrible at displaying information in a usable way so the one giant menu might not be ideal

[kizu]

I've said that already, but I'm in a process of thinking out the site's structure, the site map and the whole conception. I can't estimate when I could post there anything, as I have a lot of other work to do, but I'm thinking about the site constantly, just still not ready to sit and write the big picture down.

I don't think we hurry up anywhere, anyway :) I always like to think before do and think things through, so we won't make any unneeded work and would focus only on what really matters.

The sketches of the site map in this issue are really helpful; thank you, @corysimmons and @thefoxis for your contribution so far!

[corysimmons]

@visionmedia I think the design @mrossimojo did is solid but I think he was just using the links from the current site instead of categorized links like me and @thefoxis discussed above.

It really is a strong design for a doc site in that it's:

• clean, airy, light (like everyone in this project likes :smile: )
  • https://github.com/mojotech/stylus-redesign/issues/1#issuecomment-36903804
  • https://github.com/mojotech/stylus-redesign/issues/1#issuecomment-36893790
  • https://github.com/mojotech/stylus-redesign/issues/1#issuecomment-36905761
• uses scrollspy
• makes it easy to try

I'd honestly suggest simply reconsidering what this would look like in a perfectly clean, flexible, responsive layout, with the categorization @thefoxis came up with as links instead of the old ones.

[corysimmons]

@kizu I don't mean to offend, but the site's been in a state of disaster for years and you opened an issue related to a redesign 4 months ago.

It's sad that Sass and LESS continue to thrive so much more than Stylus, and I can't help to think that a lot of it probably has to do with first impressions.

I understand making calculated decisions, but can I please address concerns and keep this moving forward?

[kizu]

And I'm trying to maintain Stylus only for 8 months :) And I like to write down things when I think of them, not when I'm ready to do them. And I'm started to do an actual work on site just month ago by merging existing docs and using better engine at gh-pages.I perfectly understand all the current site's problems, as I'm watching all the issues there, answering numerous questions at stackoverflow and from my colleagues and seeing all their struggles. There should be a lot of work before the site and the docs would become usable and the problem is not in the design.I'm happy there are developers like you who are willing to help, so you're free to address your concerns and suggest ideas.

[Sheddybird]

Hi Guys,

Product guy hat on here, I think you've [collectively] made a fine argument for building this design.

Case being:

There is consensus that the new design is better than what we have now. This is reason enough to end the debate on this topic, and iterate now.

@kizu said,

Right now it looks almost like a skin for the existent Stylus' site, I'm not sure we need to do any actual coding before we're finished with the whole site map, features set etc."

The iterative approach here would be to ship this, then, when the enhanced 'site map, feature set etc' have been furnished, we assess those changes, build and ship again. No big deal; it should not affect work being done against any roadmap that exists. IMHO, the worst thing you could do is not enhance it now for something that might happen later.

Seems the bottom line is, if the current site is "not ideal" then let's stop apologizing for it, and ship this puppy.

_

Another take,

If there is something critically displeasing about this design, perhaps more directional feedback could help get it on the right track.

[Sheddybird]

The problem we're trying to solve is get more users using Stylus, no? Design is certainly a function of desirability, right – even for a tool. It doesn't look professional or contemporary. As a result, its promise to users becomes misaligned with its identity. It is a tool to help developers make beautiful things on the web, yet it itself does not look beautiful or credible as a tool capable of creating such things.

Again, just my .02

[tj]

It's not the end of the world that less people use it, I think the bigger problem is that what I have for a design right now is just annoying to read and doesn't highlight things very well. As far as helping users that already use Stylus or stumble upon it etc it's definitely better.

This isn't the best example since it has an ipad/video going on but I'm a fan of these full-viewport image ones lately, especially with that logo being pretty weighed it might look nice to do similar http://squarespace.com/

[Sheddybird]

Ok @visionmedia I hear you :)

To summarize, would it be a fair assessment to say that the missing element [in your estimation] isn't a beautiful Documentation Page, but rather the absence of a beautiful sell page that would get users excited about Stylus, its benefits and applications/uses?

– I think that would be a great addition to the site, and I think it's a good idea if I am understanding you correctly.

If this is the case, I think there was just a misunderstanding as to the order of operations here.

Now - we can absolutely style a handsome sell page to accompany the Documentation Page designs that @corysimmons shared. No problem. That said, would it be reasonable to suggest that we do some revisions to the Documentation Page (such that everyone involved is happy with it) so that Cory can build it. We can get that working increment up and working for us (in a marketing sense). And then @mrossimojo could move onto styling a sell page that integrates with the look and feel of the Docs. page?

– my thinking here is that in the end, you're going to want both a Sell Page and a Docs Page (and any other pages we endeavor to build) to feel like a familial, cohesive package. And because we're much farther along with the Docs page, it makes [practical] sense that we work towards delivering whichever working increment is nearest to completion, all factors being what they are.

Does that sounds reasonable @visionmedia ?

AS

[tj]

Doesn't really matter to me to be honest haha, just throwing in my opinions, I typically don't care much for flashy project websites, it's a bit of a silly way to get attention to projects that may or may not deserve it, so something usable from a docs perspective is definitely priority I'd say

[thefoxis]

I don't think it should be flashy but showing off more so-called trivia information such as getting started, how to contribute et al listed somewhere above is crucial. I think that's what makes Sass adaptation so big. Because there's a lot of docs, beginner materials and the site is friendly.

Flashy is for unexperienced designers. Design should do, not necessarily look :)

Squarespace esthetic is def a nice inspiration/direction to go. I'm happy to share the insights I got from my developer survey, which are 100% relevant here. I can also help writing content if necessary or just focus on design.

As @kizu said, some things aren't supposed to be rushed, I'm not saying we should dwell over design forever but we shouldn't try to push it too fast either.

I think @Sheddybird has a point there, and it could be a good idea to start revisiting current documentation page with new style and just implement it. Then we can build the rest incrementally rather than focus on larger website to build :)

[corysimmons]

@thefoxis :+1: Agree with everything you said. Can you share your survey results?

[thefoxis]

I haven't processed the open questions yet (so. much. data!) but, some of the interesting graphs are here:

[Sheddybird]

As this discussion moves forward, the task becomes more and more abstracted. This is a bad sign. To borrow from @thefoxis toolkit, we've gone from "do" to "talking about planning, so to possibly do in the future."

Your baseline is what is live today. It is poor. You have better. You choose not to iterate towards better, despite the virtual non-existence of any real costs.

@visionmedia references Squarespace, presumably for its presentation value, then in his next post discredits the importance of presentation, referring to is pejoratively as "flashy".

This is disillusioning.

Consider,

The opportunity cost of not acting far outweighs any futures in which we act now and update later. Updating is merely the next iteration.

One's indecision is the decision not to act.

@thefoxis if this project gets off the ground, content writing would be helpful. Sadly, must join my colleague @mrossimojo on the sidelines until folks get real about this project. Analytics sidebar : there's some interesting resources on Qualaroo's website regarding qual/quant data collection and survey methods, specifically. You might also check out the KISSmetrics blog; Neil Patel has some interesting ideas for you. With caution, I think folks like Sean Ellis and Alistair Croll would have a go at how you've crafted questions 1 and 3. Just my .02 here.

Good luck, guys.

AS

[corysimmons]

I'm not giving up yet I'll take a stab at it next. I think @thefoxis and I are on the same page.