CuttySSark
CuttySSark copied to clipboard
devinivy
Provide more informative description
I'm reading the description of your tool on your site and I'm finding it confusing.
Often events are registered using JavaScript for the sole purpose of updating styles.
The term "registering events" is ambiguous. I think you're referring to the process of binding event handlers.
The goal of CuttySSark is to allow the front-end developer to write compliant CSS that interacts seamlessly with the JS event model.
This is not a very informative statement. This could be said about most JS libraries that interact with CSS.
Registers events to apply a style block.
I have no idea what this means.
Allows remote triggering by one DOM element on another.
I have little to no idea what this means.
This selector registers a click event on #big
No. CSS selectors don't "register events". This is confusing.
From what I see, your tool is a JavaScript library which adds an on HTML attribute to certain elements based on which events fire at those elements. This is not explicitly stated on your site, but it should be.
Also, there is one unexplained aspect of your tool: How does your tool know which on values to write? Does it parse the CSS to see which event types are used in the CSS and on which elements?
This should be explained on the site.
Disclaimer: I know this may sound like a rant, but I'm just giving you an honest description of my experience with your site.
Not everyone would be interested in the technical details (I'm thinking of designers who hack some code). But it would be neat to have a 'technical' or 'how it works' page with the details you pointed out.
Perhaps saying "Adds CSS-like shorthand code for Ui interactivity" would be more clear?
You're not adding CSS-like shorthand code. That's what the developer is doing. You're providing a library that writes HTML on attributes, which then enables developers to use [on~=…] attribute selectors for their convenience.
Vague and uninformative descriptions create confusion. Confusion must be avoided. I recommend that you provide a clear and terse technical description of your tool. This is not a complex concept and designers should be able to understand it fully.
I see how some wording in the docs is confusing or unspecific, @simevidas . I will go through some of the areas you pointed out and revise them. In the meantime I'll leave this ticket open and post when I eventually update the docs. I don't plan to explain the technical details of CuttySSark in the docs right now. That's pretty rare, I think? And it's certainly not necessary information to be able to use it. I like the idea of eventually adding a "How it works" section just for those interested, per @tomByrer .
For now all will have to embrace the poetics of mystery.
