Documentation is far too thin

[tremby]

I'm using and enjoying Stylus and Nib whenever working alone on a project, but in the office we're in the process of choosing a CSS preprocessor and library to use on team projects from here on out. I wanted the choice to be Stylus but the documentation (for Stylus too, but especially Nib) is simply much too thin.

It was good enough that through reading the source and what documentation there is I was able to fumble my way through to a fairly decent understanding (I think) but the company I'm working for can't afford for the whole front end web development team to go through the same teething process.

• A good start would perhaps be to more fully document which properties are overridden (vendor prefixes automatically added, etc), and which prefixes are added for which. Maybe in matrix form.
• Clearer ideas of how syntax is made "more expressive" and "augmented" -- a formal explanation of syntax is key in addition to the couple of examples which are given in a few cases.
• Installation notes are too complicated for the simple case of a non-node site having a couple of stylesheets which want to use nib. What I've done is simply npm install nib and then I've got @import '../node_modules/nib/index.styl'. It'd be useful to include this as one of the options. Plus the neater option of using stylus -u node_modules/nib and then just @import 'nib'.

It looks like we're going to pick Sass or Less for now, but hopefully in future I can get them to switch.

[srsgores]

+1 for this. I would be willing to help out with the documentation if one of these repo owners could confirm the format they see best fit.

[notslang]

thanks for the offer, @srsgores! Markdown would be great for the docs, but if you prefer another format you could use that too.

[ibc]

Any progress on this? which is the current documentation of nib? is it just this? What about all those properties in "Miscellaneous properties"? how to use them? which syntax do they require?

[ibc]

For example, the "transaction-duration" is documented there in "Miscellaneous properties" but as far as I see nib does nothing for transition-duration: 0.5s but leaves it as it is.