nodejs / docs Goto Github PK

A place for documentation. (this repository is inactive)

License: MIT License

docs's Introduction

docs

Hi there! This repo serves as a central place for Node.js documentation coordination, but not documentation itself. The documentation for node can be found at http://nodejs.org/en/docs/. The source material is found in the node core repo.

Current Documentation WG Members

docs's People

Contributors

Stargazers

Watchers

docs's Issues

Figure out how we can measure "understandability" of code

Hey,

After the last docs WG meeting we figured out we need a better way to measure how understandable the docs are and what newcomers find confusing.

I'd like to toss around ideas for how we can measure how understandable the docs are.

Kickoff Meeting [2015-09-18 20:00 UTC]

At the Node.js Collaborator Summit, it was decided that a Documenation Working Group meeting needs to happen.

So let's do it.

Date and Time

Aug 18th, 2015, at 20:00 UTC. (See this in your local time zone.)

Participating

Participant link: https://plus.google.com/hangouts/_/hoaevent/AP36tYeG3AQAvPNE5qmWKaTc-2s7DgxyhV-MelM43peyBHJhC84DZg

Link to watch: http://www.youtube.com/watch?v=Z-nYI5Q5myM

Minutes Doc (will be in repo after meeting): https://docs.google.com/document/d/1Q1HyzOf-kjx2giZgSzg5hTY8omieux5mQRykwLHboxU/edit?usp=sharing

Email me ([email protected]) if you want edit access to the minutes doc.

Potential Attendees

Please comment here if you're interested in attending and your name's not here.

Tentative Agenda

Intros
Governance
Build/Website Integration
API Docs from core into this repo?
Overview of current open PRs.

If you'd like to add further topics, please mention so in comments.

Guide: Installing node

I would like to take the plunge and write a tutorial on installing Node as I think that this simply should be the first doc we have. What do you think?

That said I think that it pretty much resembles https://nodejs.org/download/ - how should it relate to it? Will it replace it or should we link to it for the latest versions?

Are there any topics you'd like to be covered?

A section for guides

There's an issue (nodejs/node#2165) with HFS+ where unicode paths returned by the file system are not necessarily the same as the ones that were written because HFS+ forces certain code points to be in NFD form apparently. The consensus looks to be to avoid unicode normalization in node and instead delegate the normalization task to the user.

I could litter all related methods in fs and process with a note that strings aren't necessary comparable depending on file system, but I think a better approach would be a section where we could advice on pitfalls like this.

This repo needs a readme!

I came to this repo hoping to help out with docs-writing, read the CONTRIBUTING.md, and then started poking around the repo looking for examples/some idea of the state of things.

All I found were mystifying nested folders and some old discussion on the issues. What now?

Let's put a readme in place so nobody gets lost. It can be very basic, but needs to include such information as:

What is the state of the system? Based on reading the issues, it seems we may still be pretty preliminary– is that correct?
What's a good entry point? Are there specific docs we're hoping to see written, or certain issues that need hashing out? Point me!

Onward and upward!

Create overview for "Blocking vs. non-blocking"

I'm raising my ✋ to write the overview article which was called out in this quarter's roadmap #70 - I believe my understanding is good enough from previous writing I've done on the topic.

A PR on the event loop is currently open at nodejs/node#4936 and because of the relationship between the event loop and blocking, my plan is to start on the "Blocking vs. non-blocking" overview but ultimately make sure the event loop PR is merged first and be sensitive to unnecessary overlap.

@chrisdickinson @techjeffharris sound ok to you?

Cannot find 'Event: data' or 'Event: error' in the table of contents.(api/http.html)

When I use http.request, I can get an instance of the http.ClientRequest class. Also I need handle error event like this:

req.on('error', function(e){
  console.log('Error: ' + e.message);
});

However, no Event: error in http.ClientRequest.
The same to Event: data in http.IncomingMessage.

Docs WG signup

Leave your name here if you're interested in contributing to the Docs WG.

guides: options (and default) passing patterns

A common pattern probably in any node programming style, is to pass options. Contrary to, say golang, it's rather common to pass some let options = {}. Especially on OOP js I assume this is heavily used for class instance configurations.

However, using plain js can sort of make a quick end to this approach, when used with nested objects.

Even though this might be a small guide and pattern this could lead to better style of the community if we'd advise for a solution. Object.assign(defaultObj, [...objs]) could now be nicely used for this. See examples (old and new below):

'use strict'

function oldApi (options) {
  let opts = options || {}
  opts.name = options.name || 'the default name'
  opts.test.count = options.test.count || 1
  return opts
}

let testOptions_1 = {
  name: 'better name',
  test: {
    count: 2
  }
}
console.log(oldApi(testOptions_1));

// let testOptions_fail = {
//   name: 'better name'
// }
// console.log(oldApi(testOptions_fail)); this will fail ->
// TypeError: Cannot read property 'count' of undefined

function api (options) {
  const someDefault = {
    name: 'the default name',
    test: {
      count: 1
    }
  }
  let opts = Object.assign(someDefault, options)
  return opts
}

let testOptions_2 = {
  name: 'better name',
  test: {
    count: 2
  }
}
console.log(api(testOptions_2));

// let testOptions_success = {
//   name: 'better name'
// }
// console.log(api(testOptions_success)); // this will not fail

outreach: want do promote doc WG at reddit etc.

cc/ @chrisdickinson

Even though it might not sound too sexy to contribute / express opinion to / about docs, I want to promote this thing, say at reddit. Catch phrase: "there is a doc WG now, please contribute / tell your opinion. We want to be the best docs out there". Does that seem valid to you?

Programmatic access to folders for subset of modules

I have the following scenario:

install dev dependencies (gulp, gulp-zip)
install regular dependencies (http-proxy)

  "dependencies": {
    "http-proxy": "^1.12.0"
  },
  "devDependencies": {
    "gulp": "^3.9.0",
    "gulp-zip": "^3.0.2"
  }

I have to bundle my application code, as well as the http-proxy module, into a zip file in order to upload to my server (eg. aws lambda, or my server doesn't have internet access).

I don't want to zip up all 140 directories inside of node_modules when creating my deployment package. Instead, I want to only zip up my application code, http-proxy, and http-proxy's dependencies (eventemitter3, requires-port).

Is there a programmatic way to query npm in order to return an array of folders based on an array of modules?

In this example:
getFoldersFor(['http-proxy']) -- or something --
where it would return:
['http-proxy', 'eventemitter3', 'requires-port']
so I could then only zip up those 3 folders into my application's deployment package (zip).

bundledDependencies looks like it is only for npm publishing, so that probably won't work directly.

With npm2, this was easy, as everything was nested. With npm3, there's no documented way of doing this.

Thanks!

Document header over-writing versus joining

This doesn't appear to be explained in the HTTP API docs. It should be there for clarity. For the moment, it seems that this comment in the source seems to be the only place it's mentioned.

List of Documentation Issues to Be Worked on from nodejs/iojs.org (formerly iojs/website)

I have tagged issues from the old iojs/website repo, now located at nodejs/iojs.org, with docs and invalid to indicate that they should be handled by the Docs WG, and removed them from the new.nodejs.org agenda.

These issues are still important, and need to be addressed. They just aren't in the perfect place to do so - thus, this issue has been created.

List: node/iojs.org - issues tagged with "docs"

These issues are something that I think can be taken care of by the Docs WG. Feel free to pull these into an issue or PR in this repo - if you do, though, make sure you link the issue in nodejs/iojs.org you're working from.

Internal doc guide: introducing larger features

It would be handy to have a guide that introduced "how to introduce large features into Node". It should touch on the planning process, review, and bits of implementation — for example, the use of feature flags to gate access.

Docs WG Meeting #2 - 2016-01-20 @ 10:00AM PST

Time for another meeting.

This meeting is scheduled for 2016-01-20 @ 10:00AM PST, and will be a public-viewable Google Hangout on the Air.

If you participated in the Doodle poll, then your Github username should be in this list, and you should have received an invite. If not, and you want to participate, please email me ([email protected]).

Minutes will be recorded in this Google Doc and then committed back to this repo after the meeting. Please let me know if you want write access to the doc.

Participants

Agenda

#50 WG Ratification

Migrate content files to new.nodejs.org?

There seems to be a disconnect between the website and the docs wg. I feel like it'd help to merge our content files into https://github.com/nodejs/new.nodejs.org and do all future documenting there, using this repo purely for communication and documenting the process of contributing docs. Does anyone have any strong opinions here?

I'd be happy to do the migration, if we want to go forward with it. It'd mainly just be a matter of dumping files into https://github.com/nodejs/new.nodejs.org/tree/master/locale/en/docs and adding some yaml headers to things.

@nodejs/documentation @nodejs/website

API localization: open questions

Previously handled in nodejs/nodejs.org#211. Echoing here.

Open questions were:

when we can start?
what the structure of the folder should be?
how it would be merged into main website?

Feedback: some localization groups have started the translation of API docs (iosj-ru, iojs-es). The documentation wasn't migrated over the documentation to the website group. Tooling missing at the moment.

docs: Document the Event Loop as it Relates to Node

This came up in the roadmap with #70 and I volunteered to get some content put together. I've done some local presentations on it for the JS folks in my town. I really enjoyed a talk by Philip Roberts @ JSConf EU 2014 something like that could be made more Node-centric and distilled into some GIFs for a presentation to help illustrate it.

Doctool: Remark plugins

This is a tracking issue for a new doctool using remark. The goals are:

Render the api docs as HTML roughly equivalent to the existing doctool output.
Render the guides and tutorials added to the nodejs/node repo as HTML.

This issue will contain all known breakages and necessary plugins (both existing and net new), broken into "required" and "nice to have":

Required

@include syntax (remark-include by @Qard)
Hook into Node Makefile
YAML frontmatter (for stability index)
- per-section YAML
{Type} parsing (for parity with this PR)
Basic layout selection (for switching between guides and API layouts)
Header anchors

Nice to have

Linting
- ESLint for JS code examples
- Link validation
- API Method format validator
- Make existing docs pass lint
- Hook into Node Makefile tests
- API headers — check to make sure they're in alphabetical order
Switch table of contents generation to remark-toc

Documenting benchmarking

We should document the process of benchmarking in node so we have a resource to point contributors at.

This could include such topics as

documenting test/common.js
document createBenchmark
- what magic does it give?

new topic: asynchronous programming

I would like to attempt a first version of the ~~guide~~topic to asynchronous programming.

The intended audience is javascript programmers new to node.js.

This doc would probably live at src/topics/async.md.

I'm thinking of the following rough outline:

what is async programming
- something about function returning early, results available later
why async is done in node.js
- something about servers and requests
considerations for async programming
- something about the event loop
- something about concurrent in-flight requests (and how that affects use of global resources)
- something about exceptions and stack traces
async approach: callbacks
- short intro
- link to the callback topic
- mention and then link to events
- mention and then link to streams
async approach: promises
- short intro
- link to the promises topic
async approach: ES7 async/await
- short intro
- link to the async/await topic
when synchronous is OK
- e.g. CLIs

meta: style guide

This is a continuation of #79, I've noted that there're a few styles not following (that I know of) explicit conventions.

The ones I could came up with:

what to use when refering to different values (how to format strings, how to format booleans, etc). Example: the Buffer docs uses 'true' to reference a boolean value once but mostly uses just true.
markdown used when adding code blocks (i.e. object literals, JSON). Relevant discussion nodejs/node#4733

I'm missing any?

Doc WG Slack

I've created a Docs WG Slack and invited the current members. If we decide we don't want to use this, it's totally fine — but gitter seems like it's been a ghost town, and it'd be good to have a space for continuous / real-time-ish discussion.

If you haven't received an invite, please email me at chris at neversaw dot us.

We need another meeting!

We are way overdue for another meeting. 4.x has been out for awhile now, and @nodejs/website has the keys to nodejs.org now. We need to coordinate with the Website WG to get what we've got onto the website and do something about the collaboration-unfriendly state the repo is currently in.

I've put together a doodle to find a time next week: http://doodle.com/poll/8wwpw97f62gpawrx

The agenda doc is here, please suggest more stuff to discuss:

https://docs.google.com/document/d/1TdP8dKDy24nM3Scv9I-NN-RsFbuveX8Foys01SCh-bw/edit?usp=sharing

@nodejs/documentation @nodejs/website

Missing Error Documentation

In my experience, Node.js will report many errors like EACCESS, EPIPE, etc. No where are these errors documented (what they mean and when they occur). This seems like a big issue.

Why it's a pretty significant issue is because errors is one of the most common thing developers must handle, and a vague error is the worst kind of error. I believe Node.js can do better; I think every error from Node.js core framework should be documented and explained.

PS: This is a duplication of the original issue for nodejs.org nodejs/nodejs.org#162 (comment)

Readme: update members

I just updated the members in the readme.md (didn't know that I have push rights here) according to @chrisdickinson 's lists

Minor inconsistency between Timers and Global Objects doc pages

Hello - I noticed some items on Timers are also documented on Global Objects, but not consistently.

These items are listed on both Timers and Global Objects:
clearInterval(t)/clearTimeout(t) and setInterval(cb, ms)/setTimeout(cb, ms)

But these items are listed only on Timers (missing from Global Objects?):
clearImmediate(immediateObject), setImmediate(callback[, arg][, ...]), ref()/unref()

docs: Document Timers in Node

This will track progress on a Documentation Overview of Timers in Node, as suggested in the Docs WG Roadmap for Q1 2016 (#70). Since an understanding of the Event Loop is pretty essential to giving context for timers, I'll be using nodejs/node#4936 as a branching off point to explain how timers work and best usages of the different API functions.

Here are some ideas I have for topics to cover:
Differences between intervalObject and timeoutObject and how they wrap Timer objects
Timer internals, like the linked list structure
... more to add

Any suggestions for topics are appreciated!

Documentation Tooling

Hi – I'm taking this task for myself.

I'm going to investigate documentation tooling for this repository.

Goals:

Command to build docs into html format
Command to serve docs locally
Command to test docs (for broken links, spelling, etc.)

It's pretty likely these'll live as npm scripts (npm test, npm start, npm run export, etc.)

running nodejs on embedded systems

I heard mention in the hardware wg that the docs team may be looking for someone to write a tutorial about running nodejs on embedded systems. is this accurate? I was looking to help out, but need more information.

thanks

Document initialization process

This issue will be used to track progress on documenting the internal intialization process as listed in the Roadmap (which currently can be found at #70)

I believe this documentation should include:

what happens when node is run before your code is executed
where the globals come from
process
__ values
console
what is different in the initialization of a child_process

Documentation on new.nodejs.org

Heya,

It seems prudent for this WG to take responsibility for the documentation on new.nodejs.org.

Right now this section is called "Resources" but that is not a great name and should probably be changed to something better which is also something I think we should leave to this WG to decide :)

You can name it something else by editing this file https://github.com/nodejs/new.nodejs.org/blob/master/locale/en/site.json

Creating the page is pretty simple, I would use the "About" page as a guide for how the template and build system works.

Keep in mind that all content is templatized for localizers.

Let me know if you have any questions.

Tutorial for using the built in node profiler

I recently wrote a short tutorial on how to use the built in profiling capability in node to optimize app performance. I was wondering if the docs wg were interested in including this or something similar with any other guides or tutorials you have.

Here is the tutorial: http://pastebin.com/5v3TiNY8

Trello Board of Ideas

The following is a transcription of the topics discussed at NodeConf. This board will serve as the backlog proposed documentation improvements. The list is not prioritized. As the efforts are prioritized, they will be converted into Github issues which can then be assigned to individuals and implemented.

https://trello.com/b/OK2TBRw1/node-js-documentation-brainstorm

Note: The board can be viewed by anyone but I will have to individually add people in order to grant "Edit" permissions. If you would like to add or edit the board, please leave your email below or email me at [email protected] and I will add you as a collaborator immediately.

Guide: Anatomy of an HTTP Transaction

(Not sold on the title. Ideas pls!)

I have a lot of time on planes coming up in the next few weeks so I thought I'd seize the opportunity. I'd like to put together a in-depth guide on how HTTP requests are handled. This could be a replacement for, or something to go alongside, a "Your First Webserver" guide.

I'd start it out with a very basic web server (possibly all at once, possibly bit by bit as concepts are introduced, haven't decided yet), and iterate through basically every line explaining what is going on. I want to break down the order in which things happen, which events get fired when, etc., which is often a source of confusion. I'd be gearing this toward people who are brand new to node, maybe have done a "Your First Webserver" tutorial or something (or maybe not) and want to get a better understanding of what's actually happening.

How's that sound?

docs: improving documentation of setTimeout/setImmediate/process.nextTick

There are several outstanding issues in joyent/node requesting better documentation
of setTimeout, setImmediate, and process.nextTick. Opening this to consolidate the
reports and track status. Will add links to the original issues here, but closing those
original issues.

Documentation Values

One of the action items from Nodeconf was to put together a set of values for both our docs and our team so that we've got a good basis for making decisions about the docs. I'm going to take a stab at writing this over the next day or two.

My goal will be to cover strategic values, tactical values, and mechanical values – so that any doc team member can easily use these values when determining what to start writing, how to write it, how to edit it, and what to look for when editing other's work. I will submit the style guide piecemeal to this repo as a series of PRs so that we can discuss these values.

A brief definition of terms: strategic values will influence our long-term goals for these docs. They should help us decide how to move the project forward and set priorities.. Tactical values influence the actual writing of the docs – what to write and how to approach writing it. Mechanical values are the most like a traditional style guide – how to format the documentation source, grammar rules, etc.

If folks have input ahead of the PRs, please comment here! I'll be associating all of the PRs with this issue so you'll see 'em as they pop up.

Tutorial on Using and Debugging Streams.

This is based on a twitter interaction I just had with @janl. Also suggested that @remy would have good feedback as well.

https://twitter.com/janl/status/626089572301062144

Markup to describe when APIs were introduced/changed

It would really help if the API documentation had some kind of consistent markup that described at what node version and API was introduced and or changed in a backwards incompatible way.

For example io.js newSession docs doesn't at all mention that the callback argument is new since 0.10.

Would this be a good place to report this?

The thing that is needed IMO is:

agreement that this is a problem and that inline text in the API docs is a solution
a markup template for what these notes should look like
... people can PR into the API docs on an ongoing basis using the standard markup

Information / brainstorm / input session w/ all of the “locale” groups

Crosslinking this issue here: nodejs/Intl#9

cc @nodejs/documentation

Docs Review Sign-up

As part of our charter, this WG is required to review documentation coming through PRs in nodejs/node. However, we're to avoid blocking PRs from landing solely based on documentation concerns.

As a result, I propose we start a review of docs that have landed on the master branch of Node over the course of the past week. Our goal will be to clarify, correct, and edit recently landed API docs. This should prevent the Docs WG from blocking Core contributors from landing work, while ensuring a high quality of documentation for releases. Docs to be reviewed will be reported in the Docs WG Slack.

If your interests lie in spelling, grammar, or editing, this is a task that could benefit from your skills. Please comment on this issue if you're interested in helping out with this.

Document release process

This issue will be used to track the status of created a guide to document the internal release process as outlined in the Roadmap (currently found at #70)

Currently the doc lives in docs/releases.md

V8 auto docs

I'm trying to figure out a good way to add something to our release process to auto-generate the docs for deps/v8 and dump them somewhere online. The intent is to have a folder tree something like /docs/internals/v8/{node_version} where you can view V8 docs for the relevant node/io.js version.

Challenges:

A single build is over 1GB.
Requires doxygen is installed.
Completion and accuracy of the API reference docs are unknown to me

Perhaps there could be a node service with doxygen and git already installed that watches github releases, checks out the matching commit, runs doxygen, and dumps the resulting files in S3 or something like that? Anyone have any feedback on this idea?

cc: @chrisdickinson

Docs WG Ratification

There's been a bunch of discussion with regards to getting ratified on the Node tracker.

The current proposal is:

All of our docs live within the Node repo.
- Commit cleanliness would be relaxed for authors — the person merging will clean up those commits.
This repo exists for coordination and (possibly) review of net new docs before merging into Node.
The docs team has jurisdiction over doc/, tools/docs; and shares responsibility for doc/api with the core team.
Before ratification, we do a call for membership to make sure we're including contributors that we missed over the last months.
- Once we are ratified, we can then suggest the proposed IA changes as PRs to the main repo.
  - This might be as simple as PR'ing the knowledge base & tutorials we've written up until this point into the Node repo for discussion.

While I've been in contact with a few of us, I'd like to make sure we're OK with this plan going forward.

/cc @nodejs/documentation

internal doc guide: a tour through node

I was writing up a piece, that should give new comers and example work through of how node is built and how you can traverse the stacks. It is doing this by introducing a new feature hello_world from scratch (I continued working of extending path though) with having v8, libuv, js code and hooking it into the build system.

It was missing some parts at the libuv-to-v8 level and explanations how reading in js strings with vm works. With some senior support I could actually be able to complete this.

Does that sound interesting in terms of the roadmap? #70. Also might touch the current issue of nodejs/node#4931

Documentation Roadmap

Hi all —
I've noticed that it can be overwhelming to look at the state of the docs and try to pick a single thing out to work on. There are a ton of things that need improvement, and everyone sees different deficiencies in the docs. Further complicating matters, the docs are a relatively tight space to work within — it's really easy to end up stepping on other folks' toes when making larger changes.

With that in mind, I'd like to run a quick exercise. In this issue, I'd like you to list as many different features, tools, or docs that you think need work. At this point this is unranked listing — no +1's or votes at this point, please! Feel free to repeat items others have said, though. Examples might be:

Doc tool needs to validate links
Need internationalization strategy for node docs
Create "guide" section
Create glossary, define all jargon terms within
Docs search
Better docs on child process

I will close this issue at the end of the week and put forward a roadmap for discussion.

/cc @nodejs/documentation

Document how dependencies are managed / updated

In #4765 an individual asked why a dependency was not being included as a submodule

https://github.com/nodejs/node/pull/4765/files#r50186199

Afaik we do not have the management strategy for dependencies documented anywhere.

Here is my response.

Currently for dependencies such as v8, libuv, or npm we take version updates as a single commit updating the state of the current directory, generally from a collaborator of the project we are downstream from. In between large updates we will sometimes backport changes as individual patch's.

Where should something like this live?
How specific should it be?
Should it be documented on a per vendor basis?
Should this be a standard that vendors adhere to?

edit: the last two points may be a bit out of scope for this issue, but I am concerned about how specific this should be if it is considered authoratative

Backticks confusing in examples

I've just had the second person using normal ticks instead of backticks and not understanding why examples aren't working. Template strings are a relatively new feature and people are getting confused by the examples:

I think our examples should somehow emphasize that these are backticks (not really sure how), or we should avoid backticks except when discussed in the examples, or we can have a small FAQ page for that.

As it is, users get confused. Opinions?

I can write a PR once a decision is made.

Docs WG Sign-up Round #2

Hey folks! If you're interested in joining the Docs WG — or in helping out with the Node docs in general, leave your name here. We'll onboard folks on a regular basis. Thanks!

(Previously: #2)

Docs WG Meeting #3 - 2016-02-03 @ 10:00AM PST

This meeting is scheduled for 2016-02-03 @ 10:00AM PST, and will be a public-viewable Google Hangout on the Air.

I will place the Google Hangouts link for participants in the Docs WG Slack, and link the public URL in this issue.

Minutes will be recorded in a Slack Document that will be shared in the channel, then committed back to this repo after the meeting.

We will be revisiting the time of subsequent meetings to make sure everyone invited can attend.

Invited

Docs WG Meeting #3 2016-02-02

Present

In-meeting

@chrisdickinson

In-chat

Agenda

Doctool: Remark plugins #61
Add first draft of ROADMAP.md #70
Discuss open PRs on Core (time permitting) issue tracker

nodejs / docs Goto Github PK

docs's Introduction

docs

Current Documentation WG Members

docs's People

Contributors

Stargazers

Watchers

Forkers

docs's Issues

Date and Time

Participating

Potential Attendees

Tentative Agenda

Participants

Agenda

Required

Nice to have

Invited

Docs WG Meeting #3 2016-02-02

Present

In-meeting

In-chat

Agenda

Recommend Projects

Recommend Topics

Recommend Org