documentation is oversimplified and not really useful about riak-js

[asheshambasta]

+1

[janearc]

The examples are not even really helpful from the standpoint of "I just want to do X simple task." It would be much better to have a markdown document here, on github, to look at that was higher-readability (the color scheme is difficult to read) and documented it like an API instead of advertising copy. Further, if riak-js.org goes offline for whichever, the docs, such as they are, are gone.

[Neamar]

You're right.

Maybe we should move the current readme to a changelog (or use github releases) and give some examples on the readme, that's more common on github.

Any thoughts from previous maintainers on this point?

[gigonaut]

yeah, I agree making the readme a bit more github friendly is a really good idea. Does not absolve us from doing something better with the pages branch that houses the current docs along with the domains that point to them.

[janearc]

The standard convention is a README.md file in the project root that documents each of the calls in the api. If you read the npm documentation, it goes further to suggest an example directory with obvious purposes.

I am not sure why this was not done to begin with. I'd offer to write it myself, but the library has proved difficult for me to understand at all; I just wrote my own instead.

[gigonaut]

All valid points, solid documentation is a good and important thing as is logical and consistent organization of that documentation across libraries in the space. Hopefully we will be able to get this one resolved when the riak 2 stuff goes out.

[rm-rf-etc]

I agree with the above points. I'm currently conflicted about which riak client–riak-js or nodiak–I am better off using and supporting. While this project has a good amount of activity in the issues section and a long list of people who have made small contributions, the docs and lower readability of the code itself, along with nodiak being listed / linked on the basho website (and riak-js not), has given me reason to consider nodiak more so than riak-js. I've found it easy to add support to nodiak for fetching objects using riak 2.0 bucket-types.

The main issue that I take with riak-js.org is that the examples don't cover the basics first. Document creation needs to come before metas, protobuffs, load balancing, etc. As a first-time NoSQL user, I want to create a user object, and then create a few more associated objects, do some kind of relational lookup (search), and make some updates. Instead, the order on riak-js.org is:
• create a client
• do something with a protocol buffer (I don't even know what these are yet)
• load balancing and connection pooling (I don't have a load to balance yet)
• fetch a document
• meta objects
• ...
It seems there isn't a section on creating documents. The first mention of a PUT appears to be in the section "Callbacks".

The history log in the readme is nice but would be better as a separate doc, with a 'hello world' example in the readme.

[janearc]

Please note that "being listed on the basho website" only requires submitting a PR and doesn't imply any endorsement or suitability.