Loops about less-docs HOT 9 CLOSED

@SomMeri it would be great to use some of the stuff from your blog posts. I think we should just add attribution to those sections, like:

## Looping
@credit: http://meri-stuff.blogspot.ru/2013/03/less-css-tips-and-trics.html#TricksandWorkaroundsLooping
...

from less-docs.

If @SomMeri is ok with it, I'd rather keep attribution like that to commit messages.. otherwise it gets messy when its edited and its not useful to the reader. If a blog article has more content and we want link to it, I'm totally pro that though.

from less-docs.

@lukeapage I see your point but I'm going to respectfully disagree here. I do understand why you would prefer that with less.js or in source code, but with the docs we need to give attribution when we take any kind of content from a published source to respect the legal copyright.

Aside from that, I'm not suggesting we give attribution like this for every single contribution. But even if we did, here is an example of how I do that in another project: https://github.com/assemble/handlebars-helpers/blob/master/lib/helpers/helpers-i18n.js#L15. Which, IMO isn't a bad idea.

And how it looks in the docs I did for Assemble (look for "Credit: Kegan Street" just below the block quote): http://assemble.io/helpers/helpers-data.html

from less-docs.

Now I've read what the artical is it makes more sense but I also wonder if
we are not editing it why we don't just link to it? But I don't mind if you
do it your way, its a minor opinion.

from less-docs.

yeah, that's a good point. I guess it's a matter of balance

from less-docs.

Updated mixins-recursive-loops.md so it has something to read at least. Actually I would not expand this sections beyond of one or two sentences and one or two examples, for two reasons:

• Just to not slow everything down for now.
• And in future.. hmm, I think eventually it would make sense to have a two level documetation for features (and even functions where applicable). Where the first level is just a basic less or more formal overview/synopsis/reference (i.e. "the documentation") and a second level for advanced usage; typical, classic and special examples, common pitfalls, recommendations etc. (i.e. "The LESS Book"). The disadvantage of "everything on one page" is that it unintentionally makes things to look much more comlplecated than they actually are (so that a user seeing 1000 lines of documentation for "Feature X" may unconsciously feel it's too hard for her to learn and to use). But that's in future...

from less-docs.

@jonschlinkert @lukeapage First of all, I'm sorry for delay in my responses.

On topic: you can use my blog posts on less.js or any documentation found in less4j wiki. You can both copy the content or link it.

On attribution: the in documentation attribution @jonschlinkert suggests looks nice. However, you can use the blog even if you decide not to put it there. Less.js documentation is one big page that might be restructured or rewritten later on. While it is perfectly clear what exactly was written by me, the boundaries might become less clear later. For example, someone might add more details into somebody else's section, rewrite it for better English while keeping the content and so on. It will be difficult to guess when to remove/change the contribution mark.

Another possible way to add attributions would be to create the "contributors" page which would contain simple list of people and their contributions. This would be easier to maintain I think.

from less-docs.

I like the @seven-phases-max idea of two level documentation for features and functions. New people need some kind of big picture overview "what is possible to do" and experienced less users need to reference/details.

That being said, we must be careful to structure it in a way that will not force us to write everything twice. Getting people write documentation is harder then getting them code, so the documentation should be as easy to contribute to and writing should require as little work as possible.

from less-docs.

@SomMeri thanks for being so accommodating, we'll find a good balance I think. I also want to make sure that the operative point isn't lost on this... even if the author/creator of something we use is okay with whatever kind of attribution we give, we actually have to give attribution. Not just because it's the right thing to do, but for legal reasons, and not to mention the readers of any of the things we "borrow". We definitely don't want a situation where someone thinks we're ripping someone else's stuff off.

I do however completely agree with the point @lukeapage was making, that for most situations the commit messages are enough, since they track granularly who contributed what, and how and when changes were made, and by whom.

IMO, we should not be afraid to reference whatever material we want from whatever source is above board, whenever it will help members of the community learn how to use Less.js - and equally we shouldn't even have a concern for giving attribution when we do it... I think if we just follow a simple convention this won't be a concern anymore

from less-docs.