The docs that end up in NPM are incomplete

[stubbornella]

Lets add more info about usage, etc. to the README.md (which populates the node docs)

https://npmjs.org/package/csslint

[stubbornella]

An example of good docs:
https://npmjs.org/package/request

[nschonni]

Also should add tags to the package.json for searching

[nzakas]

npm just pulls the Readme.md file. I'd caution against putting too much in
that file, as we have a whole wiki of information and I wouldn't want to
have two places for documentation (keeping in sync will be an issue). Maybe
add more descriptive information in the Readme.md with a link to the wiki?

On Tue, Mar 26, 2013 at 6:27 AM, Nick Schonning notifications@github.comwrote:

Also should add tags for searching

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/365#issuecomment-15457851
.

---

Nicholas C. Zakas
@SlickNet

Author, Professional JavaScript for Web Developers
Buy it at Amazon.com:
http://www.amazon.com/Professional-JavaScript-Developers-Nicholas-Zakas/dp/1118026691/ref=sr_1_3

[nschonni]

I'm not sure that the readme will be pulled in unless the package.json is moved to the root

[nzakas]

Good point. I'm not sure if it uses the git root or the package root. If
the latter, it'll be pretty easy to copy the file to the package root.

-N

On Wed, Mar 27, 2013 at 6:48 AM, Nick Schonning notifications@github.comwrote:

I'm not sure that the readme will be pulled in unless the package.json is
moved to the root

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/365#issuecomment-15523962
.

---

Nicholas C. Zakas
@SlickNet

Author, Professional JavaScript for Web Developers
Buy it at Amazon.com:
http://www.amazon.com/Professional-JavaScript-Developers-Nicholas-Zakas/dp/1118026691/ref=sr_1_3

[stubbornella]

Maybe it could be populated automatically from the wiki content?
—
Sent from Mailbox for iPhone

On Wed, Mar 27, 2013 at 10:24 AM, Nicholas C. Zakas
notifications@github.com wrote:

Good point. I'm not sure if it uses the git root or the package root. If
the latter, it'll be pretty easy to copy the file to the package root.
-N
On Wed, Mar 27, 2013 at 6:48 AM, Nick Schonning notifications@github.comwrote:

I'm not sure that the readme will be pulled in unless the package.json is
moved to the root

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/365#issuecomment-15523962
.

---

Nicholas C. Zakas
@SlickNet
Author, Professional JavaScript for Web Developers
Buy it at Amazon.com:

http://www.amazon.com/Professional-JavaScript-Developers-Nicholas-Zakas/dp/1118026691/ref=sr_1_3

Reply to this email directly or view it on GitHub:
#365 (comment)

[nschonni]

You could look at https://github.com/assemble/assemble if you want to change to a Node/Grunt based build

[stubbornella]

I'd love to move to grunt, but it is beyond my skillset at the moment.
—
Sent from Mailbox for iPhone

On Fri, Mar 29, 2013 at 12:05 AM, Nick Schonning notifications@github.com
wrote:

You could look at https://github.com/assemble/assemble if you want to change to a Node/Grunt based build

Reply to this email directly or view it on GitHub:
#365 (comment)

[nzakas]

I'm not sure I follow why copying content from the wiki into the README led to a discussion about Grunt. I'd like to keep this thread talking about the issue at hand: how to get better info showing on npmjs.org without duplicating content. If anyone has ideas on how to accomplish that, I'm all ears!

[nschonni]

Sorry if it was off topic, but I was suggesting something that could automatically generate the README content.

[nzakas]

I'm all for that. I'd just prefer not to rewrite the entire build system to
support one extra use case. I'm certain anything that can be done with
Grunt can also be done with our existing system. I mean, we're just talking
about fetching and/or copying files, this doesn't mean we need a completely
new system.

On Sat, Mar 30, 2013 at 11:15 AM, Nick Schonning
notifications@github.comwrote:

Sorry if it was off topic, but I was suggesting something that could
automatically generate the README content.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/365#issuecomment-15679109
.

---

Nicholas C. Zakas
@SlickNet

Author, Professional JavaScript for Web Developers
Buy it at Amazon.com:
http://www.amazon.com/Professional-JavaScript-Developers-Nicholas-Zakas/dp/1118026691/ref=sr_1_3

[stubbornella]

I guess since I wanted to move to grunt anyway, this feels more like a good excuse than a reason. ;)

[nzakas]

That's all well and good, but let's be more transparent about making major
changes. We have a mailing list of contributors that I'm sure would like to
be in on this info. Certainly burying "let's do grunt" in the middle of a
discussion about improving documentation isn't the best way to achieve
this. :)

On Sat, Mar 30, 2013 at 11:47 AM, Nicole Sullivan
notifications@github.comwrote:

I guess since I wanted to move to grunt anyway, this feels more like a
good excuse than a reason. ;)

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/365#issuecomment-15679651
.

---

Nicholas C. Zakas
@SlickNet

Author, Professional JavaScript for Web Developers
Buy it at Amazon.com:
http://www.amazon.com/Professional-JavaScript-Developers-Nicholas-Zakas/dp/1118026691/ref=sr_1_3