I searched for “aurelia script”, landed on the aurelia/script github page and saw “NPM INSTALL” immediately. Being one Guinness in, it violated my expectations of the most simple instructions possible (since simple is supposed to be the point here). So I guess you could say it failed the “one Guinness test”.
My initial thought was, “maybe the NPM INSTALL thing is targeted at contributors, and is not required for potential users”. So I went to the first linked examples on codesandbox, copied and pasted the three files into my legacy asp.net mvc code base, and tried it out. Unfortunately, it didn’t work the first time because I did not specify the root as
This morning I was able to apply the tiny bit of critical thought needed to solve the problem. I must say that this is awesome that this works as a drop-in script (esp. for my legacy project)!
I think I was expecting to see the most simple example (the first linked example) printed directly on the readme.md as three code blocks under a “Quick Start Example” header (or something like that). Having to click to another page and grok the format of codesandbox, as simple as it may be, was still an extra click into the world wide web.
It should also include a note instructing the user to make sure their “root” is setup correctly. Ex:
root: '/myvirtualdir/app.js' (in case you are using IIS locally instead of some lightweight http listener).
The codesandbox examples could still be shown as links below the most simple example.
So to summarize, I tried this at the end of the day, and that definitely impacted the experience, but I’m happy to see that it was just a very small bump in the road.