Skip to content

Instantly share code, notes, and snippets.

@rodneyrehm

rodneyrehm/iscroll-docs.md

Last active January 2, 2016 15:39
Show Gist options
  • Save rodneyrehm/8324903 to your computer and use it in GitHub Desktop.
Save rodneyrehm/8324903 to your computer and use it in GitHub Desktop.
Download ZIP
Feedback on IScroll 5 docs
Raw
iscroll-docs.md

feedback on iscroll docs:

  • if the docs were a github repo, one could fix typos etc. by sending a PR. github pages are awesome and can be given their own domain. (DalekJS.com is a repo - no effort, no webspace, just DNS)
  • I'm missing an index / table-of-contents for the API (config options and callable methods)
  • I can't link to a config option (e.g. "options.click") directly. This made you put in comments like "see below" instead of a much more convenient link.
  • I generally find "basic features" and "advanced options" to be not very meaningful headlines / groups. If I'm reading the docs, I probably have no idea what is basic and what is advanced.
  • I don't mind multiple documents (one for API, one for concepts, one for suggestions, one for demos, …)
  • the file names in the many faces of iscroll could link to the respective files on github
  • I don't understand the color coding of your callouts, what's yellow? what's green? I quite like how html5rocks handles fact/tip/recommendation blocks
  • example code looks so much better when it's syntax-highlighted. Look at PrismJS and possibly consider going with a two-space indentation.
  • I believe some comments would help make sense of the properties' meanings (e.g. in indicators)
  • if requestAnimationFrame() is not a better solution to the "immediate timeout" problem, explain why?
  • in custom events you might mention that the handlers are executed synchronously. Also "Custom Events" refer to something different (something you might want to look into) - maybe rename that to just "Events"?
  • Key bindings might mention that this really only works for a single IScroll instance on the page, as it can't distinguish between them. (there's activeElement but I'm not sure how useful that would really be)
  • Scrollbars might show some CSS - you do have a couple of requirements / suggestions to show
@cubiq
Copy link

cubiq commented Jan 8, 2014

thanks for your feedback.

at the moment the doc is in the readme.md file. you can help with typos with simple pull requests. I do not like github pages for various reasons and I don't feel compelled at using them. might change opinion in the future, but not just now.

everything else is probably just related to the fact that it's the first drafting. I hope to be able to fix things around with future revisions.

I don't understand the rAF thing though

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment