Better documentation/Documentation Independence

[stanier]

I first came across this project only a short while ago, and was initially driven off by one discerning factor: poor documentation.

I understand that the goal of the project is to write a functional open governance node.js fork and not to write a book on it, but I seriously feel that documentation is necessary, and should be mostly independent from Joyent's repo wiki and site.

I think that it is good to reference the original for purposes of documenting the platform, but there seems to be very little information about the project itself.

[naholyr]

Is that a general complaint on Node? Because I didn't feel this low quality :(

Anyway, any subjective advice apart, I think moving the project to open governance means moving documentation along the same way. Code + project should be a single entity to me. So 👍

[rumkin]

👍. It should be rewritten to markdown for better accessibility at least.

[stanier]

@naholyr I'm not complaining about node or it's documentation or any of that. I'm just saying that io.js should have it's own basic level of documentation.

It has the potential to surpass node or branch off in a completely separate development path, and I think it would be better to at least provide the basics (installing, FAQ, description, configurations, etc).

For instance, what if it was decided to add additional launch parameters that node doesn't have? Node's documentation wouldn't have record of it, so users wouldn't have a clue about the changes unless they searched the code for it.

[sam-github]

@rumkin the docs are in markdown: https://github.com/iojs/io.js/tree/v0.12/doc/api

I agree the docs are poor. PRing improvements to them is going to help, opening issues about it is unlikely to help. I've been PRing improvements to them. Node's docs are a WIP.

@stanier is there some specific information you failed to find?

Note that iojs hasn't built a release or a doc site yet from this source, but all the mechanisms are there. The entire nodejs.org site is generated from the doc/ folder of joyent/node, and io.js contains the same source and scripts. I assume when a site is created from which to download releases, the docs will be on that site.

[cjihrig]

Closing, as there doesn't seem to be a particular takeaway from this issue. Documentation improvements are always welcome.