4 ms·

Do they really need more than a single README.md file? Many of those modules are so small that anything more than a single README of documentation would be exce

Do they really need more than a single README.md file? Many of those modules are so small that anything more than a single README of documentation would be excessively verbose. I've never ran into the problem of feeling a module was poorly documented. The especially complex modules usually have more extensive documentation on their website. I'd say there are cases that are terrible or useful documentation for sure, but in general most modules are very good about it from my experience.

twerquie 12y ago
I agree with this. The surface area of most modules is small enough to be covered in a README.md, which is displayed prominently on npmjs.org, github.com and a copy of it is in your ./node_modules folder. As said earlier, the core Node.js framework has great documentation, as do other frameworks such as Mongoose and Express.
- vkjv 12y ago
  I agree with everything you say except for Mongoose. Mongoose lacks a lot of documentation on the fringe use cases. However, the beauty of open source is that you can just read the code, which, in my experience, is the most reliable documentation.
Monkeyget 12y ago
I want to write a simple node application that fetches an http document and write it to the disk. The only requirement is for the application to print out in plain English if there is one of the following error: * the document doesn't exist * there is a connection error during download * the local file couldn't be opened * an error occured during writing. For any other error(out of memory,...) the program can crash. How do I do that in node? I don't know. The request package only tells me the callback's first parameter is "An error when applicable (usually from http.ClientRequest object)". The fs package only tells me "Event: 'error': Emitted if there was an error when writing or piping data." I only picked error reporting as an example so I could showcase the problem of lack of documentation on the most basic APIs (http get and writing file). By the way the Error Handling article [0] on Joyent's website is absolutely wonderful. Call me old fashioned but how can I use an API that doesn't tell me which function to call, what a function accepts as parameters, what it returns or how it signals error? [0] https://www.joyent.com/developers/node/design/errors https://www.joyent.com/developers/node/design/errors
- jhchen 12y ago
  HTTP has standard error codes that tell you why a file didn't download (ex. 404 means it doesn't exist). File systems behave similarly (ex. ENOENT). None of this is language specific and therefore do not belong in Node.js documentation (except perhaps to say that these Node.js libraries also adhere to the same standards everyone else does but this is obvious the moment one of these error objects is printed or inspected).
  - nawitus 12y ago
    >but this is obvious the moment one of these error objects is printed or inspected The point of documentation is that you don't have to run the code to see what the code does.

twerquie 12y ago

I agree with this. The surface area of most modules is small enough to be covered in a README.md, which is displayed prominently on npmjs.org, github.com and a copy of it is in your ./node_modules folder. As said earlier, the core Node.js framework has great documentation, as do other frameworks such as Mongoose and Express.

vkjv 12y ago
I agree with everything you say except for Mongoose. Mongoose lacks a lot of documentation on the fringe use cases. However, the beauty of open source is that you can just read the code, which, in my experience, is the most reliable documentation.

Monkeyget 12y ago

I want to write a simple node application that fetches an http document and write it to the disk. The only requirement is for the application to print out in plain English if there is one of the following error: * the document doesn't exist * there is a connection error during download * the local file couldn't be opened * an error occured during writing. For any other error(out of memory,...) the program can crash. How do I do that in node? I don't know. The request package only tells me the callback's first parameter is "An error when applicable (usually from http.ClientRequest object)". The fs package only tells me "Event: 'error': Emitted if there was an error when writing or piping data." I only picked error reporting as an example so I could showcase the problem of lack of documentation on the most basic APIs (http get and writing file). By the way the Error Handling article [0] on Joyent's website is absolutely wonderful. Call me old fashioned but how can I use an API that doesn't tell me which function to call, what a function accepts as parameters, what it returns or how it signals error? [0] https://www.joyent.com/developers/node/design/errors https://www.joyent.com/developers/node/design/errors

jhchen 12y ago
HTTP has standard error codes that tell you why a file didn't download (ex. 404 means it doesn't exist). File systems behave similarly (ex. ENOENT). None of this is language specific and therefore do not belong in Node.js documentation (except perhaps to say that these Node.js libraries also adhere to the same standards everyone else does but this is obvious the moment one of these error objects is printed or inspected).
- nawitus 12y ago
  >but this is obvious the moment one of these error objects is printed or inspected The point of documentation is that you don't have to run the code to see what the code does.