node.js API documentation clean up

[Norbert Fuhs]

I don't think the node.js GitHub wiki and API reference documention are:

1. beginner friendly

2. easy to read

3. explain exactly what the modules does and for what it is for 

Is there an up to date list of undocumented methods and properties in  the node.js API reference documentation?

Most node.js stuff i learned is from blogs and node.js related books, i think we need better and more structured documention like the

the docs and tutorials in the Mozilla Developer Network or the Chrome Developer Tools for node.js.

[mscdex]

On Saturday, June 21, 2014 7:19:43 PM UTC-4, Norbert Fuhs wrote:

Is there an up to date list of undocumented methods and properties in  the node.js API reference documentation?

If they were in the documentation they wouldn't be undocumented ;-)

[Mark Hahn]

It has driven me crazy for years the the api docs (methods) are in no particular order, at least none that I can discern.  I usually have to scroll through most of the list to find anything.  Why not list them alphabetically?

[Aria Stewart]

On 21 Jun 2014, at 19:19, 'Norbert Fuhs' via nodejs <nod...@googlegroups.com> wrote:

> I don't think the node.js GitHub wiki and API reference documention are:
>
> 1. beginner friendly

This is hard -- beginner with what context?

I'd love to see documentation made this way, but it's a big job.

> 2. easy to read

I happen to love the current style, but I could see other styles being MUCH more effective for others -- but this is subjective, so it's not easy to get consensus on in the abstract.

>
> 3. explain exactly what the modules does and for what it is for

What it does ... well, that I think it covers.

What it's for, though, ends up leading toward prescriptive documentation, which I don't think is appropriate. People think of new uses all the time, so it's not always great to have a finite list published right there.

>
>
> Is there an up to date list of undocumented methods and properties in the node.js API reference documentation?

No -- they're undocumented because they're not part of the public API. The documentation defines the public API.

> Most node.js stuff i learned is from blogs and node.js related books, i think we need better and more structured documention like the
> the docs and tutorials in the Mozilla Developer Network or the Chrome Developer Tools for node.js.

That'd be nice to see, for sure! I'd love to see improvements, too. Not sure I want THOSE, but good resources are awesome (And we can have multiple, for different audiences)

Thoughts?

[Matt]

API docs are very different to tutorials (which sounds like what you're after). To me the docs used to be a weak point, but now they tend to be pretty good (not perfect, but there's barely anything undocumented any more).

I personally feel that it's up to the community to provide tutorials - and there's plenty of those around. Try nodebeginner.org.

Matt.

--
Job board: http://jobs.nodejs.org/
New group rules: https://gist.github.com/othiym23/9886289#file-moderation-policy-md
Old group rules: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines
---
You received this message because you are subscribed to the Google Groups "nodejs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to nodejs+un...@googlegroups.com.
To post to this group, send email to nod...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/c6b99e4d-6114-40d5-96c6-eaf8d4e8d6da%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Matt]

On Sun, Jun 22, 2014 at 2:10 AM, Mark Hahn <ma...@hahnca.com> wrote:

It has driven me crazy for years the the api docs (methods) are in no particular order, at least none that I can discern.  I usually have to scroll through most of the list to find anything.  Why not list them alphabetically?

Your comment has been out of date for a while now. Check again.

[mscdex]

The module methods and events aren't alphabetical, just the main module index. I'm not sure there is any specific order to the module methods/events currently except in a few cases where similar methods are grouped together (e.g. ref() and unref(), and multiple method signatures for the same method name -- such as net.connect()).

[Mark Hahn]

> similar methods are grouped together

It should be totally alphabetic.  You can take care of related methods by using links like "See Unlink".

--

Job board: http://jobs.nodejs.org/
New group rules: https://gist.github.com/othiym23/9886289#file-moderation-policy-md
Old group rules: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines
---

You received this message because you are subscribed to a topic in the Google Groups "nodejs" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/nodejs/Wg-W2xxZdEY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to nodejs+un...@googlegroups.com.

To post to this group, send email to nod...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/ef5ddf92-2ee2-4b27-8b0a-19f193f6e996%40googlegroups.com.

[Alex Kocharin]

 

Similar/related things are grouped together, i.e. (in case of net) ref/unref, listen/close/address, maxConnections/connections/getConnections.

 

You don't usually need alphabetic order when you have Ctrl+F, but grouping is very useful as is.

 

 

23.06.2014, 08:32, "Mark Hahn" <ma...@hahnca.com>:

--

Job board: http://jobs.nodejs.org/
New group rules: https://gist.github.com/othiym23/9886289#file-moderation-policy-md
Old group rules: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines
---

You received this message because you are subscribed to the Google Groups "nodejs" group.

To unsubscribe from this group and stop receiving emails from it, send an email to nodejs+un...@googlegroups.com.

To post to this group, send email to nod...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/31691f42-f804-4d9a-87ea-a9cdc50c8e17%40googlegroups.com.

[José F. Romaniello]

Here is another that I like a lot

http://devdocs.io

El jun 24, 2014 7:42 AM, "José F. Romaniello" <jfroma...@gmail.com> escribió:

I agree with Alex. I also use this thing to read offline which has a nice search feature

http://kapeli.com/dash

I know there are some similar products.

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/4093931403594823%40web5h.yandex.ru.

[Rebecca Turner]

Let me just concur with Alex,

As someone who reads documentation like literature when getting up to speed on a new project...

I'm not fond of alphabetizing API docs, I'd rather them to be done in related chunks, from most commonly used to least commonly used.

I'm actually not sure I understand the value of alphabetizing them, given that if you know the name already you can search the page.

-- Rebecca

You received this message because you are subscribed to the Google Groups "nodejs" group.

To unsubscribe from this group and stop receiving emails from it, send an email to nodejs+un...@googlegroups.com.

To post to this group, send email to nod...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/CACrj35E7wvnd-3wBWF%3D3cZiFToMZaQUw0%2BkW%2B_SK%3Dq%3DyL-hgzA%40mail.gmail.com.

[José F. Romaniello]

I agree with Alex. I also use this thing to read offline which has a nice search feature

http://kapeli.com/dash

I know there are some similar products.

El jun 24, 2014 6:06 AM, "Alex Kocharin" <al...@kocharin.ru> escribió:

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/4093931403594823%40web5h.yandex.ru.

[Matt]

On Mon, Jun 23, 2014 at 2:25 PM, mscdex <msc...@gmail.com> wrote:

The module methods and events aren't alphabetical, just the main module index. I'm not sure there is any specific order to the module methods/events currently except in a few cases where similar methods are grouped together (e.g. ref() and unref(), and multiple method signatures for the same method name -- such as net.connect()).

Ah right - yeah I can see why that might be confusing for modules that are just a pack of methods (unlike say HTTP, which has a bunch of classes documented inside it). Well, at least they fixed the ordering of the main page, eh? :)

[Mark Hahn]

> You don't usually need alphabetic order when you have Ctrl+F,

That's a serious PITA.

You received this message because you are subscribed to a topic in the Google Groups "nodejs" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/nodejs/Wg-W2xxZdEY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to nodejs+un...@googlegroups.com.

To post to this group, send email to nod...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/4093931403594823%40web5h.yandex.ru.

[Mark Hahn]

> As someone who reads documentation like literature when getting up to speed on a new project...

That is what tutorials are for and there are a zillion on the web.  Why are almost all others in alphabetic order?  I assume to look something up quickly without the hassle of ctrl-F.  

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/etPan.53a98bf9.643c9869.139%40Sierra-2.local.

[Mark Volkmann]

I agree with Mark. Besides Node.js, I also do AngularJS development. I'm very glad that their documentation is in alphabetical order. https://docs.angularjs.org/api

On Tue, Jun 24, 2014 at 11:25 AM, Mark Hahn <ma...@hahnca.com> wrote:

> As someone who reads documentation like literature when getting up to speed on a new project...

That is what tutorials are for and there are a zillion on the web.  Why are almost all others in alphabetic order?  I assume to look something up quickly without the hassle of ctrl-F.  

--
R. Mark Volkmann
Object Computing, Inc.

[Darren]

The docs look similar to man pages. The grouping by concept is ideal for initial through-reading, but an alphabetical index / appendix would be a really useful addition for quick reference, too. Different use cases with known solutions.

[Stephen Belanger]

It’s two key presses. Is that really so much effort?

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/CACrj35F_E7NAxLVnPugGFW2aXp3s4_OoP3m9Z0oXQNuVKYEDgQ%40mail.gmail.com.

[Rebecca Turner]

On June 25, 2014 at 12:47:27 AM, Mark Hahn (ma...@hahnca.com) wrote:

> As someone who reads documentation like literature when getting up to speed on a new project...

That is what tutorials are for and there are a zillion on the web.

I beg to differ. I much prefer to learn from reference material. Tutorials are almost entirely useless to me.

  Why are almost all others in alphabetic order?  I assume to look something up quickly without the hassle of ctrl-F.  

Hassle? I dunno, I guess it never occurred to me that Ctrl-F/Command-F would introduce meaningful friction. I find it a lot faster then scrolling through an even alphabetized list.

-- Rebecca

[Mark Volkmann]

It's not two key presses. It's two key presses plus typing the name of the thing you want to find versus scrolling.

---

R. Mark Volkmann

Object Computing, Inc.

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/BC7A0A3A71DC48A5A5428C6CE556CBCD%40stephenbelanger.com.

[Rebecca Turner]

On June 25, 2014 at 6:54:59 AM, Darren (drder...@gmail.com) wrote:

The docs look similar to man pages. The grouping by concept is ideal for initial through-reading, but an alphabetical index / appendix would be a really useful addition for quick reference, too. Different use cases with known solutions.

This sounds like a good middle ground, no?

-- Rebecca

[Mark Hahn]

> It’s two key presses. Is that really so much effort?

It's two plus how many letters you need to specify what you are looking for, which I never know.  It's just a PITA.  I can't argue why, I just know it is for me and I assume many others used to alpha sorts.

On Tue, Jun 24, 2014 at 3:49 PM, Darren <drder...@gmail.com> wrote:

The docs look similar to man pages. The grouping by concept is ideal for initial through-reading, but an alphabetical index / appendix would be a really useful addition for quick reference, too. Different use cases with known solutions.

--

Job board: http://jobs.nodejs.org/
New group rules: https://gist.github.com/othiym23/9886289#file-moderation-policy-md
Old group rules: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines
---
You received this message because you are subscribed to a topic in the Google Groups "nodejs" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/nodejs/Wg-W2xxZdEY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to nodejs+un...@googlegroups.com.
To post to this group, send email to nod...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/a20ec73f-7642-4586-a490-58b418d9dfe4%40googlegroups.com.

[Matt]

On Tue, Jun 24, 2014 at 4:09 PM, Mark Volkmann <r.mark....@gmail.com> wrote:

I agree with Mark. Besides Node.js, I also do AngularJS development. I'm very glad that their documentation is in alphabetical order. https://docs.angularjs.org/api

It's hard to believe the Angular docs are being held up as a better example! ;-)

(in fairness they have improved a lot lately, either that or I got a lot better at Angular)

[greelgorke]

Why is everyone is freaking out about search vs. sort?

first: why not have both? look at the books: most of them have a table of content (where topic are usually grouped by topics/relatedness), plus they have an index with important terms and word sorted alphabetically.

second: go and fork it, make a PR. i doubt TJ wouldn't like to see better doc structure.

for me, the main flaw of the api docs is that important notes are hard to find in the text, because they are hidden in the prose.

[Matt]

On Tue, Jun 24, 2014 at 9:59 PM, Rebecca Turner <m...@re-becca.org> wrote:

> As someone who reads documentation like literature when getting up to speed on a new project...

That is what tutorials are for and there are a zillion on the web.

I beg to differ. I much prefer to learn from reference material. Tutorials are almost entirely useless to me.

I totally agree for me personally too, but to do that requires a great understanding of the underlying technology. You need to know what you're looking for. For those who don't understand what stat(2) is, they wouldn't know to look for fs.stat() to get the size of a file. But I don't think Joyent/Node core needs to provide tutorials. There are plenty of those, and books too.

Matt.