search

static-dev / axis

terse, modular & powerful css library
http://axis.netlify.com
Other
320 stars 45 forks source link

Improve documentation examples #301

Closed reubano closed 7 years ago

reubano commented 8 years ago

Hi, I'm trying to follow along with the examples but copy/pasting them doesn't produce the displayed result.

dbox commented 8 years ago

Hey @reubano

Maybe something is off in how you're importing axis? Can you try this Codepen sandbox and reproduce any issues?

http://codepen.io/dbox/pen/pbOYwP

reubano commented 8 years ago

Hmmm, this example makes things a lot clearer. I was putting the stylus code into my jade templates. I think that's one area that should be clarified in the docs. For example coming from Bootstrap, its hard to understand what goes where in Axis.

jescalan commented 8 years ago

It does say in the repo description that it's a stylus library, and we have very extensive docs on how to use and configure it. Do you think there are any ways other than these to make it more clear?

reubano commented 8 years ago

It does say in the repo description that it's a stylus library

Similarly, Bootstrap is a LESS library but the examples are designed to go into your template file.

and we have very extensive docs on how to use and configure it

I'm trying out roots so the configuration part was already taken care of

Do you think there are any ways other than these to make it more clear?

Be more like Bootstrap docs. If you compare their button example:

<a class="btn btn-default" href="#" role="button">Link</a>
<button class="btn btn-default" type="submit">Button</button>
<input class="btn btn-default" type="button" value="Input">
<input class="btn btn-default" type="submit" value="Submit">

to yours:

.selector
  button()

.selector
  button: green 'large'

vs what you supplied in the codepen:

<a href="#" class="btn">Im a button</a>
.btn
  button()

You can see that the axis docs assume the user already has the appropriate template setup and intuitively knows the code presented should go in a stylus file. This is complicated by the fact the roots uses jade templates which has syntax similar to that of stylus. Whereas with Bootstrap, I can copy and paste the example as is and it just works.

jescalan commented 8 years ago

@reubano This makes a lot of sense, thanks for providing a clear example of what you were talking about here. I definitely see where you are coming from. Would you be willing to take a crack at a pull request to introduce this type of change into axis' docs?

Here's the repo: https://github.com/jescalan/axis-www

reubano commented 8 years ago

Would you be willing to take a crack at a pull request to introduce this type of change into axis' docs?

Can't make any promises just yet. But if I'm able to decipher enough to get this website built, I'll be happy to contribute my learnings.

jescalan commented 8 years ago

@reubano awesome, looking forward to it!