search

assemble / assemble

Get the rocks out of your socks! Assemble makes you fast at web development! Used by thousands of projects for rapid prototyping, themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websites/static site generator, an alternative to Jekyll for gh-pages and more! Gulp- and grunt-friendly.
http://assemble.io/
MIT License
4.24k stars 278 forks source link

public facing site has missing images #284

Closed jfroom closed 10 years ago

jfroom commented 11 years ago

Several place holder graphics on bottom of page. Perhaps someone is already aware. assemble-io-placeholders

jonschlinkert commented 11 years ago

yeah we'll be putting examples up there soon. any ideas?

jfroom commented 11 years ago

It may leave a better impression to omit that 'coming soon' example sites section until it's ready?

A few more observations on the topic of first impressions. Take 'em or leave 'em =]

It may help by integrating the copy "static site generator for grunt.js" in homepage hero section - not sure if that's a gross oversimplification. According to my limited knowledge, assemble is leading in that niche at the moment. That copy should also help boost the ranking for this search: http://goo.gl/1J2bBR

Comparatively, I found Middleman's documentation (diff product, but similar application) a bit easier to consume. Less whitespace/smaller fonts == less scrolling == more focused reading; clearer code examples near top of pages; docs split into a basic/advanced sections more approachable. The assemble docs start by diving into the complex options/config instead of the template aspects which may be easier to digest up front. Just my two bits.

Happy Thursday!

On Thursday, August 15, 2013, Jon Schlinkert wrote:

yeah we'll be putting examples up there soon. any ideas?

— Reply to this email directly or view it on GitHubhttps://github.com/assemble/assemble/issues/284#issuecomment-22708637 .

jonschlinkert commented 11 years ago

All good thoughts. thanks!

jonschlinkert commented 11 years ago

Btw, regarding this:

I found Middleman's documentation (diff product, but similar application) a bit easier to consume.

if you have a moment, would you mind jotting down specific things that you would have liked to have known initially? and was "noise" to you, or got in the way of getting to what you wanted?

thanks

jfroom commented 11 years ago

Again, this is all first impressions and preference - both of which are totally subjective. I'm a noob with grunt/node and admittedly still finding my footing. I'm sure there is greatness here - the more I look through this stuff, the more I realize.

For my purposes, I was looking for a static site generator and it took me a few minutes to realize this would fill that goal.

This may be my reading preference, but the first thing I do when trying to read the docs is hit 'zoom out' on my browser 3x. I know there is a trend for bigger type and lots of white space - but IMHO, I find it doesn't work as well when reading is the objective. For instance, I find the Jekyll site to be nearly impossible to speed read because of layout and design choices: http://jekyllrb.com/

Purely cosmetic (and easily dismissed if I'm just missing the bigger picture), but moving the templating section up in the side nav (above config and data) would have made more sense to me. Not sure if that messes up some logic flow though. Something about the layout that also throws me, is that when looking at the template section, the template subsections links are hidden down the page in the side nav. Putting a 'table of contents' at the top of the section pages would help and reduce the distraction of scrolling around. Middleman does a good job of breaking these down and getting majority of navigation system above the page fold. For reference: http://middlemanapp.com/templates/ http://assemble.io/docs/Templates-Overview.html

The generators, example repo, boilerplates are great. These are what got me up and running. I came back to the docs later when I wanted more detail - but I stumbled around in the docs for a while first before finding the examples. This is purely my fault - I was quickly scanning the site trying to ascertain if this tool would fill my needs.

Lastly, it would be great if the site could read my mind and organize itself to meet my needs =] Joking aside, you guys are doing great work. Carry on!

HTH

jonschlinkert commented 11 years ago

there is a trend for bigger type and lots of white space

Yeah I wasn't a fan of it either, but it was intended to provide a better experience on smaller devices - but I haven't even had a chance to fix the responsive styles yet... so no gain there.

moving the templating section up in the side nav (above config and data) would have made more sense to me.

I'll give it a shot. We're still getting to know our user base, which seems to be mix of developers and designers. The intent was to start out with config info that is more relevant to developers who are familiar with Grunt. But I can see how putting the template info up higher would make sense to any user. thanks

the template subsections links are hidden down the page in the side nav. Putting a 'table of contents' at the top of the section pages would help and reduce the distraction of scrolling around.

yes, this is something I don't like either. I have been working on a navigation helper to provide a better nav experience, that should solve part of it. I'm also working on a TOC helper that plucks the headings out of markdown and constructs a TOC on the fly. which is the main challenge, e.g. being able to continue writing the documentation in markdown while also being able to construct dynamic elements of the site like what you're saying.

This is purely my fault

well, not really. the experience should be intuitive and valuable for any new visitor. if you're familiar with saying: "the curse of knowledge", it just means that once you learn something it's quite literally impossible to remember how you saw things before you learned it. This, IMO, is the most difficult aspect of writing good documentation. Remembering what you struggled with as a new user. So feedback from new users is essential for the docs to improve.

This isn't documented, but assemble can actually read minds, and bake cookies. Lol, thanks for the feedback, and keep it coming!

jonschlinkert commented 11 years ago

hey @jfroom I just wanted to let you know I'm working on some stuff per your suggestions. my wife and I are expecting a baby any day now though, so it will be a few weeks before I'm back at full speed. however, you have some great suggestions and I'd love it if you decided to contribute in some way. I'm really open to anything. I just figured I'd throw that out before things get really busy for me. thanks!

haustraliaer commented 11 years ago

@jfroom "I'm a noob with grunt/node and admittedly still finding my footing. I'm sure there is greatness here - the more I look through this stuff, the more I realize."

I was in almost exactly the same place a month or so ago and I can tell you it's absolutely worth pushing through with this plugin... Assemble just seems to keep on giving the more I use it.

That being said I completely agree with the state of the docs - it was quite hard to penetrate some of this stuff from the outside looking in, so to speak.

My business partner and I, both designers before we were programmers, intend to try and contribute back to the project with some "assemble for designers" type documentation, framed in an example repo of how we've been using it in our workflow.

Hopefully that will help a few people pick it up more easily and take some slack off these devs!

jonschlinkert commented 11 years ago

thanks @haustraliaer!

btw, on the topic of examples, I wanted to point out this project: https://github.com/assemble/buttons. If you poke around a bit in this repo, you'll see that each example builds on the last. so IMO it might be a good place to start for new users of assemble.

jonschlinkert commented 10 years ago

quick progress report on this:

jonschlinkert commented 10 years ago

docs have been reworked, we'll be publishing soon. closing so that any further discussion can take place on that repo