I would love more documentation

[DjebbZ]

Hi

Amongst all the project I saw wrapping IndexedDB, yours is the most tested but one of the less documented. It's like using db.js requires a non-trivial knowledge of IndexedDB, plus a knowledge of how to use db.js itself.

An example, as I'm just starting to use it : when using db.open, the server and version are required, but the schema. I had the read all the open-db.js spec file to learn how to create a database. Not very cool for a library that tries to simplify the usage of complex API.

But worry not, this comment is not a rant, rather a proposal of help. I'd like to write some public facing docs so that people effectively don't need to read code/specs to use it. Just need approval and some guidance about how you see it.

Sidenote : your project seem to be compatible with the IndexedDBShim, which is pretty cool, and one of the reason I choose to use your project.

[brailateo]

@DjebbZ I agree with you that this project looks just fine, I took a look inside at the code and it's well organised and I hope too that this project will be used more as soon as possible. Aaron is doing a very good job so I also want to help him develop this library, I'm testing it and write demos so if I can help you sending the demos to you in order to extend the howto documentation, just ask.

[DjebbZ]

I'd be happy to ! Reading your code will surely help me understand even more of db.js and IndexedDB in general, so it's cool.

I think I will just start documenting as exhaustively as I can the basic API along my usage of them : db.open, server.query, 'server.query`, etc. As a new user in the browser storage field, I have everything to learn, so I think I'm at the good moment to write docs.

[aaronpowell]

That's for the support guys! I am aware that documentation is what's really lacking on this project, I'm just like every dev, docs are always the last thing I want to deal with :P.

I've gotta get the github pages updates, in the mean time there's a bunch of useful stuff available here

[DjebbZ]

Didn't you had a blog. The articles are quite interesting. I'll consider it being my documentation for the time being. About real docs, do you envision something in particular ? My experience tells me that there should always be only one single source of truth when it comes to documentation, or docs will just be impossible to maintain. Where do you see this source : in code, having it generated using JSDoc, Docco, or Dox (a mix of the two) ? In the Github Wiki ? In the already existing github page ? In the README ?

I would propose the github page, it's just more readable (and your theme is nice !)

[aaronpowell]

Well if you check out the source you'll see that there's no comments in it so currently those tools wont be any good :P.

I've just done a very quick overhaul of the GH pages, but I might have a look at whether or not it'll be possible to do a JSDoc/ Dox site, but the problem I'm seeing is that many of the "types" are internal, and since it's a chaining API it could be a bit tricky to get it to generate anything useful.

[brettz9]

I think this issue can be closed now since the README has been enhanced to cover the API. There are already issues for Docco generation (issue #21 ) and for porting your blog (issue #19 ).

[DjebbZ]

Indeed, README looks complete with regard to usage and API. No interest in db.js now, but closing anyway to keep the issues clean. Thanks for the reminder.