Open Sourcing the documentation

[Kerim Gueney]

Documentation is often neglected by developers and open sourcing them in a repo like this one allows for people (like me) who enjoy documenting software to contribute to the project :-)

[Aaron Bartell]

We would LOVE for somebody to take up the documentation.

At the end of the day we need it in markdown format, though we haven't yet decided where it will go (this wiki, a *.md file in this repo, readthedocs.io, etc).

Would you be willing to convert the docs on developerWorks to markdown?

[Jesse G]

I would propose embedding the doc in the code and using ESDoc to generate good HTML... but then the question isçwhere would it be hosted?

Here is a good example of ESDoc in action: http://reactivex.io/rxjs/class/es6/Notification.js~Notification.html

If we like this idea, I know there are several similar solutions and I am not bound to ESDoc if others have a different preference.

[Kerim Gueney]

@aaronbartell

I wouldn't mind converting the existing docs to markdown, I'll try and do it some time soon!

I also like @ThePrez 's suggestion. I mean, we could do both because an API reference is definitely necessary but I'm also sure many appreciate a more verbose documentation along with examples in the style of the current docs.

[Musse]

@KerimG I am also working on Documenting the newly made idb-pconnector which is a promised based version of the current idb-connector.

Check it out here : https://bitbucket.org/litmis/nodejs-idb-pconnector/overview

We can coordinate and get both idb versions Documented with examples.

[Kerim Gueney]

Saw in #2 that @InfernoSpirit has volunteered to do the documentation. Is he going to do it all? Should I contact him for coordination?

Also, I'd like to mention again that I like @ThePrez 's idea . My only question is, is ESDoc the right tool considering the source code of the idb-connector isn't in JavaScript?

[Kerim Gueney]

I got in touch with @InfernoSpirit and I'm going to do the docs. Can someone adjust the repository permissions or so, so that I can fork?

[Jesse G]

Thanks, @KerimG! I've added you to the "team" for this repo. You should be able to fork the project by following the '+' icon from the upper left.

[Jesse G]

@KerimG, thanks again for taking this! I am assigning this issue to you, but please coordinate with willing-to-help @abmusse to complete the documentation for this repo as well as the nodejs-idb-pconnector (I think it'd be great if we used the same conventions for both).

[Jesse G]

@KerimG and @abmusse , I propose we follow the same conventions for the Javascript API's. Do you agree?

[Kerim Gueney]

@ThePrez

What exactly do you mean? Do you have a concrete example or are you saying that this project and nodejs-idb-pconnector should follow the same conventions? If it's the latter, I agree. Regarding your ESDoc suggestion: you could host the generated docs on Bitbucket's static website hosting or GitLab Pages (I've always been a big fan of GitLab, even more so after Microsoft's acquisition of Github)

Sorry for being inactive in the past few months. I joined a company in the AS400 sphere at the beginning of the year and my work load increased rapidly in May. I will try to make time for the docs, though!

[Jesse G]

@KerimG, sorry for the unclear update. I'm just saying that this project and pconnector should follow the same conventions. I like the pconnector API doc's format and layout:

https://bitbucket.org/litmis/nodejs-idb-pconnector/src/master/docs/main.md

We'll need to do our own invention or reuse for further doc of the generated code.

No apology needed on the inactivity. It's better to be busy than bored!

[Musse]

@ThePrez Started the process of porting the Docs from Developer works. See PR #6

[Aaron Bartell]

Marking this as resolved. The docs are now in this repo and can subsequently be massaged by core committers and PRs.