├── .editorconfig ├── CONTRIBUTING.md ├── GETTING-STARTED.md ├── GOVERNANCE.md ├── LICENSE ├── README.md ├── ROADMAP.md ├── assets ├── code-examples │ └── .gitkeep ├── css │ └── .gitkeep ├── img │ └── .gitkeep └── js │ └── .gitkeep ├── meetings └── 2015-08-18.md └── src ├── guides ├── .gitkeep └── anatomy-of-an-http-transaction.md ├── meta ├── reference │ └── .gitkeep └── topics │ ├── .gitkeep │ └── dependencies.md ├── reference └── .gitkeep └── topics └── .gitkeep /.editorconfig: -------------------------------------------------------------------------------- 1 | 2 | # What is this file? 3 | # see http://editorconfig.org/ 4 | 5 | # What formatting rules are we trying to follow? 6 | # see https://github.com/nodejs/node/tree/master/doc/STYLE_GUIDE.md 7 | 8 | 9 | # don't look for more .editorconfig files in parent directories 10 | root = true 11 | 12 | 13 | # default formatting for all file types 14 | [*] 15 | end_of_line = lf 16 | insert_final_newline = true 17 | charset = utf-8 18 | 19 | 20 | # formatting for markdown files 21 | [*.{md,markdown}] 22 | indent_style = space 23 | indent_size = 2 24 | trim_trailing_whitespace = true 25 | 26 | 27 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to the Docs 2 | 3 | If you're reading this, you want to contribute to the docs. That's great! Take 4 | a second to pat yourself on the back, then go [read the guide][]. We'll wait. 5 | 6 | ... OK, cool. 7 | 8 | Once you've read the guide, you should be able to comfortably answer why we're 9 | writing docs here, what sort of docs we write, and how we go about writing 10 | them. If you're unclear on any of that, [open an issue][] with questions! 11 | 12 | This document exists to walk you through the process of how contributions work 13 | in this repo – including [some assertions][] about what we expect you to be 14 | able to claim about your work, and [some guidelines][] for how to interact with 15 | others while you're here. This document will address five goals: 16 | 17 | 1. "I want to [**change** a doc][]!" 18 | 2. "I want to [**write** a doc][]!" 19 | 3. "I want to [**join** the team][]!" 20 | 4. "I want to [**review** a doc][]!" 21 | 5. "I want to [**merge** changes][]!" 22 | 23 | What's common to all of them is the process to expect on the tracker: 24 | 25 | 1. The author submits a change to the repository in the form of a PR. 26 | 2. A reviewer will review the changes and may make suggestions. 27 | 3. Once a reviewer has given the work a "LGTM" stamp of approval, 28 | 1. if the author has the ability to merge, they may merge the work at this 29 | point. 30 | 2. if the author does not have access, the reviewer should merge the work. 31 | 32 | If you have questions at **any point** – whether it's about this process or 33 | about a specific doc – [open an issue on the tracker][]. Remember, you're doing 34 | the project a **favor** by asking questions – other people might have the same 35 | question in mind, and this gives the docs team a chance to see how effective 36 | the documentation is. 37 | 38 | ## To **change** a document: 39 | 40 | 1. *Fork* the appropriate repository to your account. 41 | 1. This is usually . 42 | 2. *Clone* your fork. 43 | 3. Make your changes locally. 44 | 4. *Commit* your changes to a new branch. 45 | 5. *Push* that branch to your repository. 46 | 6. *Open* a PR. 47 | 1. Make sure you include a description of *why* you're making the changes. 48 | 7. Respond to feedback by making edits and pushing them to your local branch. 49 | 1. When you're done making requested edits, *comment* "Ready for review!" on 50 | the PR. 51 | 8. Once your reviewer comments "LGTM" your changes are ready to merge. 52 | 1. Not all changes will be merge-able – don't be discouraged! Closed PRs 53 | are not "failed" PRs – they're valuable feedback, both for the submitter *and* 54 | the reviewer. Closed PRs help tell the project what it is just as much as 55 | merged PRs. 56 | 2. Your PR will also be subject to the contribution rules of the repository 57 | you're making it on, so be mindful of them. 58 | 59 | ## To **write** a document: 60 | 61 | 1. *Open* an issue on this repository describing the sort of document you'd like 62 | to write. 63 | 1. Include details about what audience you're addressing, 64 | 2. what idea you'd like to convey to that audience, 65 | 3. where you'll put the document, 66 | 4. and how other docs will relate to it. 67 | 5. Consult [the guide][] for, er, guidance on what to write. 68 | 2. Gather feedback on your proposed document! 69 | 1. If you're fairly confident that your proposed document is *relevant* and 70 | *helpful*, go ahead and start working on it. 71 | 2. If you're unsure, note your uncertainty in the issue, and wait for feedback 72 | to see whether the document is needed before starting work on it. 73 | 3. To start work on your document, follow the [above process][] for **changing** a 74 | document. 75 | 76 | ## To **join** the team: 77 | 78 | If you'd like to join the documentation team, that's great! Note your interest 79 | [on this issue][]. We'll get in contact with you shortly afterwards. Note that 80 | as part of the team, you are expected to be an *exemplar* of the project's 81 | values – both in making this specific project a welcoming place to contribute, 82 | as well as in the larger community (other issue trackers, conferences, etc.) 83 | 84 | The full details of membership access and responsibilities are listed in 85 | [the `GOVERNANCE.md` file][docs-governance]. 86 | 87 | ## To **review** a document: 88 | 89 | 1. If a PR already has an assigned team member, post a comment on the PR asking 90 | that team member if it's okay for you to help. 91 | 1. If the other team member says it's OK, then procede. 92 | 2. Otherwise, if you still have concerns, contact the team member via email 93 | with your review-related concerns. If your concerns are team-member-related, 94 | direct them to the [nodejs/diversity working group][]. 95 | 2. If the PR does not have an assigned member, feel free to assign yourself! 96 | Once you are assigned to a PR, you are fully responsible for the success of it. 97 | 3. Begin the editing loop: 98 | 1. Read the entire document. 99 | 2. Make structural comments first. 100 | 3. If you have no structural comments, make grammar and spelling comments. 101 | 4. Once you are done reviewing, 102 | 1. If you've commented, comment "review done." 103 | 1. Once the author comments to the effect of "ready for review," 104 | restart the editing loop. 105 | 2. If you have no further comments, you may: 106 | 1. Ask another team member to review. It's usually best to 107 | get two LGTMs before merging. 108 | 2. Comment "LGTM", and: 109 | 1. If the author is not a team member, [merge their changes][]. 110 | 2. If the author is a team member, they may merge their own changes. 111 | 112 | Guidelines for commenting on work: 113 | 114 | * Your goal as an editor is to make the documentation serve our audience 115 | better. 116 | * Secondary to that, your goal is to make the review process a painless, 117 | successful experience for the author. 118 | * This means commenting on the *work*, not the *author*. 119 | * If the work does not make the documentation better for our audience overall, 120 | * Explain why it does not, 121 | * and suggest other avenues the author can follow to achieve their goal. 122 | * "Success" means the author felt their effort was valued, not necessarily 123 | that the PR was ultimately merged. 124 | * Respect the author's time and effort. Be kind. 125 | * Speak objectively, and try to back up your comments with examples. 126 | * If you don't agree with the author, consider that you might 127 | not understand their point of view. Try to get them to explain further, or in 128 | different terms, so that you might better understand them. 129 | * Avoid condescension (and the appearance of condescension.) Communicate as 130 | equals. 131 | 132 | ## To **merge** changes: 133 | 134 | For this repository, once a PR has a LGTM, any team member in full standing may 135 | merge it. Team members under mentorship may merge with the permission of their 136 | mentor. 137 | 138 | Patches may be merged using the big green GitHub merge button if there are no 139 | conflicts. 140 | 141 | If there are conflicts, the PR should be updated to resolve any conflicts, and 142 | should be briefly re-reviewed before merging. 143 | 144 | For other repositories, their processes for merging apply. 145 | 146 | ## Developer's Certificate of Origin 1.0 147 | 148 | By making a contribution to this project, I certify that: 149 | 150 | * (a) The contribution was created in whole or in part by me and I 151 | have the right to submit it under the open source license indicated 152 | in the file; or 153 | * (b) The contribution is based upon previous work that, to the best 154 | of my knowledge, is covered under an appropriate open source license 155 | and I have the right under that license to submit that work with 156 | modifications, whether created in whole or in part by me, under the 157 | same open source license (unless I am permitted to submit under a 158 | different license), as indicated in the file; or 159 | * (c) The contribution was provided directly to me by some other 160 | person who certified (a), (b) or (c) and I have not modified it. 161 | 162 | 163 | ## Code of Conduct 164 | 165 | Before jumping into the rest of the Code of Conduct, it is important to note 166 | that the values of this project are derived from the values of the Node.js 167 | project at-large. As those change, so ours will change to reflect them. 168 | 169 | Once they are documented, they will be linked to from here. 170 | 171 | This Code of Conduct is adapted from [Rust's wonderful 172 | CoC](http://www.rust-lang.org/conduct.html). 173 | 174 | * We are committed to providing a friendly, safe and welcoming 175 | environment for all, regardless of gender, sexual orientation, 176 | disability, ethnicity, religion, or similar personal characteristic. 177 | * Please avoid using overtly sexual nicknames or other nicknames that 178 | might detract from a friendly, safe and welcoming environment for 179 | all. 180 | * Please be kind and courteous. There's no need to be mean or rude. 181 | * Respect that people have differences of opinion and that every 182 | design or implementation choice carries a trade-off and numerous 183 | costs. There is seldom a right answer. 184 | * Please keep unstructured critique to a minimum. If you have solid 185 | ideas you want to experiment with, make a fork and see how it works. 186 | * We will exclude you from interaction if you insult, demean or harass 187 | anyone. That is not welcome behaviour. We interpret the term 188 | "harassment" as including the definition in the [Citizen Code of 189 | Conduct](http://citizencodeofconduct.org/); if you have any lack of 190 | clarity about what might be included in that concept, please read 191 | their definition. In particular, we don't tolerate behavior that 192 | excludes people in socially marginalized groups. 193 | * Private harassment is also unacceptable. No matter who you are, if 194 | you feel you have been or are being harassed or made uncomfortable 195 | by a community member, please contact one of the channel ops or any 196 | of the TC members immediately with a capture (log, photo, email) of 197 | the harassment if possible. Whether you're a regular contributor or 198 | a newcomer, we care about making this community a safe place for you 199 | and we've got your back. 200 | * Likewise any spamming, trolling, flaming, baiting or other 201 | attention-stealing behaviour is not welcome. 202 | * Avoid the use of personal pronouns in code comments or 203 | documentation. There is no need to address persons when explaining 204 | code (e.g. "When the developer") 205 | 206 | [nodejs/diversity working group]: https://github.com/nodejs/diversity 207 | [read the guide]: GETTING-STARTED.md 208 | [open an issue]: https://github.com/nodejs/docs/issues/new 209 | [some assertions]: #developers-certificate-of-origin-10 210 | [some guidelines]: #code-of-conduct 211 | [**change** a doc]: #to-change-a-document 212 | [**write** a doc]: #to-write-a-document 213 | [**join** the team]: #to-join-the-team 214 | [**review** a doc]: #to-review-a-document 215 | [**merge** changes]: #to-merge-changes 216 | [open an issue on the tracker]: https://github.com/nodejs/docs/issues/new 217 | [the guide]: GETTING-STARTED.md 218 | [above process]: #to-change-a-document 219 | [on this issue]: https://github.com/nodejs/docs/issues/2 220 | [nodejs/diversity working group]: https://github.com/nodejs/diversity 221 | [merge their changes]: #to-merge-changes 222 | [GOVERNANCE.md]: GOVERNANCE.md 223 | [docs-governance]: ./GOVERNANCE.md 224 | -------------------------------------------------------------------------------- /GETTING-STARTED.md: -------------------------------------------------------------------------------- 1 | # Node Documentation 2 | 3 | Welcome to the Node.js Documentation Guide — or less formally, the docs on 4 | docs. If you're here, you're likely looking for guidance on how to write 5 | documentation for the project. You're in luck! This is where we house all of 6 | that information. 7 | 8 | This guide is divided into sections for **why** we're writing docs, **what** we 9 | want to write, and **how** we write it. 10 | 11 | * If you're new here, start from the top with the [Why We Write Docs section][] 12 | and go down. 13 | * If you're ready to write some docs but don't know what to write, look at the 14 | [What We Write section][]. 15 | * If you have a formatting or grammar question, look at the 16 | [How We Write section][]. 17 | 18 | ## Why We Write Docs 19 | 20 | Documentation serves many audiences in many different ways — and we recognize 21 | that. For some, the docs are their introduction to Node, and they want to know 22 | what all the fuss is about. Others might be learning to program for the first 23 | time. Still others may simply use the reference documentation we provide as a 24 | sort of cache for information otherwise available in the source code of the 25 | project. 26 | 27 | We write docs because we want to include people from each of these audiences in 28 | our community, we want to make their lives better, and we want them to walk 29 | away from the docs with a positive attitude about the Node community. We want 30 | this not just out of empathy for our fellow human beings, but also out of 31 | self-preservation: the health of Node hinges on how useful it is, and how 32 | useful it is depends on how easy it is for folks to use it! If folks can't 33 | figure out how to use Node, they walk away from it, and then we have to start 34 | writing for a different platform which might not be nearly [as fun][]. 35 | 36 | To summarize: 37 | 38 | * Our audiences are **diverse** and have **different goals** coming into the 39 | docs. 40 | * We write docs so that our audiences can have a **positive experience** with 41 | Node. 42 | * We want them to have a positive experience with Node out of **empathy** and 43 | **self-preservation**. 44 | 45 | ## What We Write 46 | 47 | A solid strategy around structure is key to building good documentation. 48 | Authors must know where to put a topic before they can start writing it — they 49 | need to know the larger context of how the reader will get to that document. 50 | Misplaced documentation won't be found, or, more disastrously, will appear 51 | interleaved in other documentation, which is hugely confusing! 52 | 53 | For that reason, we split our writing into three categories: 54 | 55 | 1. **Guide** documents explain processes to help the reader learn a concept in 56 | service of their larger goal. Usually a guide has the reader build something — 57 | a little webserver, or CLI — and explains the concept it's trying to convey 58 | using examples from the readers experience with that code. Guides are great for 59 | introducing new concepts in a comfortable way, by letting the reader "simulate" 60 | the process of what development will be like using those concepts. 61 | [Django's getting started guide][] is a great example of this, though it doesn't 62 | necessarily have to be aimed at beginners. 63 | 2. **Topic** documents explain concepts to help the reader make a decision. 64 | They are a great place for "deep dive" information, and to handle anything 65 | that's fairly intricate. 66 | 3. **Reference** documents explain capabilities to help the reader achieve 67 | their goal. API documentation is the primary example of this. 68 | 69 | Every document we author should address **one primary audience** and describe 70 | **one complete idea**. If a document starts to address two audiences or ideas, 71 | it can quickly become confusing and hard to maintain. Documents that start to 72 | transform in this way should be **split up**. When a document about a topic 73 | starts to describe two ideas, the core concept of both should become a 74 | directory that documents for both ideas are put into. For example: 75 | 76 | topics/streams.md -> 77 | topics/streams/using-a-stream.md # for users of streams 78 | topics/streams/writing-a-stream.md # for authors of streams 79 | topics/streams/index.md # links to both of the above 80 | 81 | In other cases, in order to explain an API, reference documentation may need to 82 | describe a larger topic. In that case, the topic should be described 83 | separately, as a document in `topics/`, and linked to from the reference in 84 | `references/`. This is especially true when multiple references need to 85 | describe the same topic! 86 | 87 | We believe good documentation is fractal. Guides, topics, and reference may all 88 | repeat that organization internally, so long as it does not interfere with the 89 | communication of the core idea of the document. For example, it's good to add 90 | links to reference materials at the end of topic docs, but it would be unwise 91 | to enumerate a module's entire list of methods inside that same doc. Another 92 | example: it's great to include *brief* example code in the reference 93 | documentation, but it is not so great to include a full program there. 94 | 95 | To summarize: 96 | 97 | * Structure is of paramount importance. 98 | * Decide on an **audience** and an **idea** you want to convey to that 99 | audience. 100 | * If the reader is to follow a process to get to a goal, it's a **guide.** 101 | * If what you're writing conveys a concept to help the reader in decision 102 | making, it's a **topic.** 103 | * When the reader is consulting your document to find a specific piece of 104 | information, it's **reference.** 105 | * Each document should clearly convey *one* idea to *one* audience. All 106 | strategies are in service of that goal. 107 | 108 | ## How We Write 109 | 110 | Please adhere, as best as possible, to the [style guide][]. 111 | 112 | ### Tone 113 | 114 | The tone of your writing should change in service of the goal of the document. 115 | For example, *guides* may be warm and whimsical in order to make the reader 116 | comfortable and pique their interest. *Reference material* should adopt a 117 | terser, more clinical tone, in order to more efficiently convey information to 118 | the reader. *Topics* are halfway between the two — a more neutral tone may be 119 | adopted, but it's okay to mix some humanity in as well! 120 | 121 | ### Introducing Changes 122 | 123 | To introduce changes, open a PR to this repository. One "LGTM" comment from 124 | another team member is sufficient to merge a change. When describing your 125 | change, make sure to note why you are making the change in the description. If 126 | you are writing a new doc, please include a one-to-three sentence paragraph 127 | explaining the idea you are attempting to convey and the audience you are 128 | targeting. For more information on this, see [CONTRIBUTING.md][]. 129 | 130 | [as fun]: https://twitter.com/izs/status/187639633641865216 131 | [CONTRIBUTING.md]: CONTRIBUTING.md 132 | [style guide]: https://github.com/nodejs/node/tree/master/doc/STYLE_GUIDE.md 133 | [Why We Write Docs section]: #why-we-write-docs 134 | [What We Write section]: #what-we-write 135 | [How We Write section]: #how-we-write 136 | [Django's getting started guide]: https://docs.djangoproject.com/en/1.8/intro/tutorial01/ 137 | -------------------------------------------------------------------------------- /GOVERNANCE.md: -------------------------------------------------------------------------------- 1 | # Documentation Working Group 2 | 3 | The Node.js Documentation group is jointly governed by a Working Group (WG) 4 | which is responsible for high-level guidance of the project. 5 | 6 | The WG has final authority over this project including: 7 | 8 | * Technical direction 9 | * Project governance and process (including this policy) 10 | * Contribution policy 11 | * GitHub repository hosting 12 | * Conduct guidelines 13 | * Maintaining the list of additional Collaborators 14 | 15 | For the current list of WG members, see [the project README.md][nodejs-docs-]. 16 | 17 | ## Membership 18 | 19 | ### Joining the WG 20 | 21 | Membership may be extended by current WG members to individuals who have made 22 | contributions to documentation in the Node or JavaScript communities who **have 23 | expressed interest in membership**. Candidates for membership will be approved 24 | or denied by existing WG members using the [Consensus Seeking 25 | Process][consensus] process below. Individuals may express interest publicly on 26 | the [sign-up issue][sign-up] or privately to any existing Docs WG member. Put 27 | simply: **if you are a documentarian and are willing to fulfill the 28 | [responsibilities of membership][membership-responsibilities] to the best of 29 | your ability, the Docs WG would be happy to receive your help.** 30 | 31 | The Docs WG encourages prospective members to read the 32 | [CONTRIBUTING.md][nodejs-doc-contributing] and 33 | [GETTING-STARTED.md][nodejs-doc-getting-started] documents for an idea of how 34 | the WG operates. 35 | 36 | ### Membership Access and Responsibilities 37 | 38 | Membership in the Node.js Documentation WG entails the following access: 39 | 40 | * Membership in the [Node.js Documentation Slack][nodejs-doc-slack]. 41 | * Membership in the **@nodejs/documentation** GitHub team. 42 | * Collaboratorship on the [Node.js Documentation Repository][nodejs-doc-repo]. 43 | 44 | Members should prepare to take part in the following activities, to the best of 45 | their abilities: 46 | 47 | * Attend meetings in the form of Google Hangouts. 48 | * Coordinate via [**nodejs/docs** issues][nodejs-doc-repo]. 49 | * Coordinate with WG members via [Slack][nodejs-doc-slack]. 50 | * Respond to pull requests, and issues on the **nodejs/node** tracker that: 51 | * are tagged with the `doc` label, OR 52 | * have cc'd **@nodejs/documentation**, OR 53 | * modify the `doc/` or `tools/docs` directory. 54 | * Apply the [editing standards][nodejs-doc-standards] recommended by the WG to 55 | all documentation review. 56 | * Keep the [goals][nodejs-doc-goals] set by the WG in mind when contributing 57 | documentation. 58 | 59 | **The WG recognizes that this is largely a volunteer effort, and will endeavour 60 | to adjust the time commitment of participation in the WG to reflect that.** If 61 | you would like to contribute, but cannot participate in one or more of the 62 | above tasks, please contact a WG member. The WG will attempt to make 63 | accomodations for interested individuals. *Members are not required to be 64 | collaborators on the `nodejs/node` repository.* 65 | 66 | Members are expected to conduct themselves according to the [Docs WG Code of 67 | Conduct][nodejs-doc-coc] as well as any Code of Conduct set by the larger Node 68 | Foundation. The Code of Conduct is enforced by the [Moderation 69 | WG][nodejs-moderation]. Any Docs WG member banned from the Node project by the 70 | Moderation WG will also be removed from the Docs WG. To report a violation of 71 | the Code of Conduct, please [follow the steps listed 72 | here][nodejs-moderation-request]. 73 | 74 | ### Membership Collaboration 75 | 76 | #### Documentation Review and Copyediting 77 | 78 | Follow the process outlined in [CONTRIBUTING.md][nodejs-doc-contributing]. 79 | 80 | #### Changes to Docs WG Guidelines and Process 81 | 82 | Modifications of the contents of the Node.js Documentation WG repository are 83 | made on a collaborative basis. Anybody with a GitHub account may propose a 84 | modification via pull request and it will be considered by the project 85 | Collaborators. All pull requests must be reviewed and accepted by a 86 | Collaborator with sufficient expertise who is able to take full responsibility 87 | for the change. In the case of pull requests proposed by an existing 88 | Collaborator, an additional Collaborator is required participate if there is 89 | disagreement around a particular modification. [See _Consensus Seeking Process_ 90 | below][consensus] for further detail on the consensus model used for 91 | governance. 92 | 93 | Collaborators may opt to elevate significant or controversial modifications, or 94 | modifications that have not found consensus, to the WG for discussion by 95 | assigning the `wg-agenda` tag to a pull request or issue. The WG should serve as 96 | the final arbiter where required. 97 | 98 | #### Additional Membership Constraints 99 | 100 | WG seats are not time-limited. There is no fixed size of the WG. There is no 101 | specific set of requirements or qualifications for WG membership beyond rules 102 | set forth in this document. 103 | 104 | The WG may add additional members to the WG by unanimous consensus. 105 | 106 | A WG member may be removed from the WG by voluntary resignation, by unanimous 107 | consensus of all other WG members, or by ruling from the Node.js Moderation WG. 108 | 109 | Changes to WG membership should be posted in the agenda, and may be suggested as 110 | any other agenda item (see "WG Meetings" below). 111 | 112 | No more than 1/3 of the WG members may be affiliated with the same employer. If 113 | removal or resignation of a WG member, or a change of employment by a WG member, 114 | creates a situation where more than 1/3 of the WG membership shares an employer, 115 | then the situation must be immediately remedied by the resignation or removal of 116 | one or more WG members affiliated with the over-represented employer(s). 117 | 118 | #### WG Meeting Agenda 119 | 120 | Items are tagged with `wg-agenda` which are considered contentious or are 121 | modifications of governance, contribution policy, WG membership, or release 122 | process. 123 | 124 | The intention of the `wg-agenda` tag is not to seek approval or review all 125 | patches proposed - that should happen continuously on GitHub and be handled by 126 | the larger group of Collaborators. 127 | 128 | Any community member or contributor can ask that issues be tagged with the 129 | `wg-agenda` tag by asking in the respective GitHub Issue. Any Collaborator, WG 130 | member or the moderator can add the item to the agenda by adding the `wg-agenda` 131 | tag to the issue themselves. 132 | 133 | The moderator is responsible for summarizing the discussion of each agenda item 134 | and send it as a pull request after the meeting. 135 | 136 | A regular cadence will be determined for meetings by consent of the WG. 137 | 138 | #### Consensus Seeking Process 139 | 140 | The WG follows a [Consensus Seeking][external-consensus] decision making model. 141 | 142 | When an agenda item has appeared to reach a consensus the moderator will ask 143 | "Does anyone object?" as a final call for dissent from the consensus. 144 | 145 | If an agenda item cannot reach a consensus a WG member can call for either a 146 | closing vote or a vote to table the issue to the next meeting. The call for a 147 | vote must be seconded by a majority of the WG or else the discussion will 148 | continue. Simple majority wins. 149 | 150 | Note that changes to WG membership require unanimous consensus. See "WG 151 | Membership" above. 152 | 153 | [consensus]: #consensus-seeking-process 154 | [sign-up]: https://github.com/nodejs/docs/issues/2 155 | [membership-responsibilities]: #membership-access-and-responsibilities 156 | [nodejs-doc-slack]: https://nodejs-docs.slack.com/ 157 | [nodejs-doc-repo]: https://github.com/nodejs/docs 158 | [nodejs-doc-standards]: https://github.com/nodejs/docs/blob/master/GETTING-STARTED.md#how-we-write 159 | [nodejs-doc-goals]: https://github.com/nodejs/docs/blob/master/GETTING-STARTED.md#why-we-write-docs 160 | [nodejs-doc-coc]: https://github.com/nodejs/docs/blob/master/CONTRIBUTING.md#code-of-conduct 161 | [nodejs-moderation]: https://github.com/nodejs/moderation 162 | [nodejs-moderation-request]: https://github.com/nodejs/TSC/blob/master/Moderation-Policy.md#requesting-moderation 163 | [nodejs-doc-contributing]: ./CONTRIBUTING.md 164 | [nodejs-doc-getting-started]: ./GETTING-STARTED.md 165 | [external-consensus]: http://en.wikipedia.org/wiki/Consensus-seeking_decision-making 166 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright io.js contributors. All rights reserved. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to 5 | deal in the Software without restriction, including without limitation the 6 | rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 7 | sell copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in 11 | all copies or substantial portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 18 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 19 | IN THE SOFTWARE. 20 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # docs 2 | 3 | Hi there! This repo serves as a central place for Node.js documentation 4 | coordination, but not documentation itself. The documentation for node can be 5 | found at . The source material is found in the 6 | [node core repo][]. 7 | 8 | ## Current Documentation WG Members 9 | 10 | * [**@a0viedo**](https://github.com/a0viedo) 11 | * [**@ashleygwilliams**](https://github.com/ashleygwilliams) 12 | * [**@bengl**](https://github.com/bengl) 13 | * [**@benjamingr**](https://github.com/benjamingr) 14 | * [**@chrisdickinson**](https://github.com/chrisdickinson) 15 | * [**@danielkhan**](https://github.com/danielkhan) 16 | * [**@danjenkins**](https://github.com/danjenkins) 17 | * [**@DavidTPate**](https://github.com/DavidTPate) 18 | * [**@distracteddev**](https://github.com/distracteddev) 19 | * [**@drewfish**](https://github.com/drewfish) 20 | * [**@eljefedelrodeodeljefe**](https://github.com/eljefedelrodeodeljefe) 21 | * [**@estliberitas**](https://github.com/estliberitas) 22 | * [**@evanlucas**](https://github.com/evanlucas) 23 | * [**@jasisk**](https://github.com/jasisk) 24 | * [**@kahwee**](https://github.com/kahwee) 25 | * [**@kelthenoble**](https://github.com/kelthenoble) 26 | * [**@kosamari**](https://github.com/kosamari) 27 | * [**@MylesBorins**](https://github.com/MylesBorins) 28 | * [**@Qard**](https://github.com/Qard) 29 | * [**@rdodev**](https://github.com/rdodev) 30 | * [**@rodmachen**](https://github.com/rodmachen) 31 | * [**@romankl**](https://github.com/romankl) 32 | * [**@rubo-21**](https://github.com/rubo-21) 33 | * [**@ryansobol**](https://github.com/ryansobol) 34 | * [**@snostorm**](https://github.com/snostorm) 35 | * [**@stevemao**](https://github.com/stevemao) 36 | * [**@techjeffharris**](https://github.com/techjeffharris) 37 | * [**@thefourtheye**](https://github.com/thefourtheye) 38 | * [**@tomgco**](https://github.com/tomgco) 39 | 40 | [node core repo]: https://github.com/nodejs/node 41 | -------------------------------------------------------------------------------- /ROADMAP.md: -------------------------------------------------------------------------------- 1 | # Docs WG Roadmap 2 | 3 | ## Jan 2016 → Apr 2016 (Q1) 4 | 5 | This is the first of the quarterly roadmaps that this Working Group will 6 | produce, so it will be structured a bit differently than subsequent ones. Since 7 | this is a brand-new process, an explanation of **what it is** and **why it's 8 | necessary** follows. 9 | 10 | This roadmap outlines the priorities for the Docs working group for the 11 | quarter. These tasks can be as broadly or narrowly defined as is useful. They 12 | are not necessarily staffed — as folks step up to do the work, we'll link 13 | tracking issues to the tasks for them to self-organize. Every quarter we'll 14 | revisit this roadmap, adding a quick postmortem of how things went, and 15 | creating a new set of priorities for the ensuing quarter. 16 | 17 | That brings us to why a roadmap is necessary: the Node.js documentation is a 18 | relatively confined space to work within, and there are many interested 19 | parties: there are groups that consume the documentation as output, like the 20 | [website working group][wg-website], there are groups concerned with ensuring 21 | the [content addresses the needs of diverse audiences][wg-inclusivity], there are 22 | [groups that are required][wg-ctc] to produce API documentation as a 23 | pre-requisite to merging their primary work, there are contributors who wish to 24 | help in a _technical_ fashion, there are contributors who wish to contribute 25 | _editorially_, and there are the readers of the docs. All of these 26 | contributions overlap, so in order to make measurable progress without stepping 27 | on each other's feet, we have to: 28 | 29 | * **Set clear priorities** — if two contributions conflict, it should be 30 | straightforward to determine which contribution should take precedence. 31 | * **Message these priorities well in advance** — with this many stakeholders, 32 | we should mention repeatedly, loudly, and clearly what our intentions are. 33 | The Docs WG should aspire to avoid surprise. 34 | * **Make the best use of donated time** — we want to ensure that if someone is 35 | donating their time to improve the documentation, it will be well-spent, and 36 | directed at driving the documentation towards this WG's [stated goals][goals]. 37 | 38 | [Our goals][goals] can be summarized thusly: 39 | 40 | > Node.js should be in friendly competition for "Best Docs in OSS," with docs 41 | > that address the needs of a wide variety of audiences — across skill levels, 42 | > goals, and languages. 43 | 44 | ### Tasks 45 | 46 | Tasks for this quarter were drawn from [responses to this issue][issue-roadmap]. 47 | They are divided between three major areas: 48 | 49 | * **Content** — the actual content of the docs 50 | * **Features** — reader-focused features, like version metadata or autolinking. 51 | * **Tooling** — author-focused features, like doc linting or html generation. 52 | 53 | Since **content** is the ultimate product of this WG, it will usually be the 54 | highest priority. However, when **content** systemically fails audiences, it 55 | may point to a need for better **features** or **tooling**. 56 | 57 | **Right now, our features and tooling are lacking, and the content is suffering 58 | for it.** 59 | 60 | #### :one: Pulling Guides into [nodejs/node][repo-nodejs] 61 | 62 | **This is our highest priority over the next two months.** 63 | 64 | Right now the documentation is split between the [website repo][wg-website] and 65 | the [core repo][wg-ctc]. We wish to bring the [guide documentation][guide-docs] 66 | into the core repo. 67 | 68 | The existing [node doctool][ref-doctool] is specifically built to _only_ 69 | generate API docs. Until we can build the guide docs with Node.js' `make doc` 70 | command, guide documentation will be copied from the website repo into the core 71 | repo, but not *removed* from the website repo. 72 | 73 | As a result, we are investigating using [remark][ref-remark] to build the 74 | docs. The stages of this project are as follows: 75 | 76 | 1. Use remark to build just the guides alongside the existing doctool. 77 | 2. Remove the guides from the website repository. 78 | 3. Identify and install the necessary remark plugins to faithfully render the 79 | API documentation. 80 | 4. Generate all documentation using remark. Fix lint issues pointed out by 81 | `remark-lint`. 82 | 5. Once no linting issues remain, wire up docs linting as part of Node.js' 83 | `make test`. 84 | 85 | Once this project is complete, all doc style rules will be handled by remark, 86 | which includes line lengths, code samples (via eslint), markdown bullet and 87 | emphasis styles, and link checking. We will have a solid basis on which to add 88 | spelling and grammar checkers in the future, making it easier to maintain the 89 | docs going forward. 90 | 91 | ##### Subtasks 92 | 93 | Want to pitch in? Look here! If someone's already working on the task, see 94 | if they need help. 95 | 96 | * Identifying Remark plugins — **@qard**, others! [nodejs/docs#61](https://github.com/nodejs/docs/issues/61) 97 | * Initial Remark integration — **@qard** [nodejs/node#4866](https://github.com/nodejs/node/pull/4866) 98 | * Codify linting rules 99 | * Apply linting rules across API docs 100 | * HTML layout for guide docs 101 | * HTML layout update for API docs to include refs to guide docs 102 | 103 | #### :two: Guide and Topic Docs 104 | 105 | A _very_ close second to the work on the documentation tooling is the work on 106 | identifying and creating new guides and topic documentation. These two terms 107 | come up a lot, to clarify what they mean, here's an except from our [getting 108 | started][ref-getting-started] guide: 109 | 110 | > 1. **Guide** documents explain processes to help the reader learn a concept 111 | > in service of their larger goal. Usually a guide has the reader build 112 | > something — a little webserver, or CLI — and explains the concept it's trying 113 | > to convey using examples from the readers experience with that code. Guides 114 | > are great for introducing new concepts in a comfortable way, by letting the 115 | > reader "simulate" the process of what development will be like using those 116 | > concepts. 117 | > 2. **Topic** documents explain concepts to help the reader make a decision. 118 | > They are a great place for "deep dive" information, and to handle anything 119 | > that's fairly intricate. 120 | > 3. **Reference** documents explain capabilities to help the reader achieve 121 | > their goal. API documentation is the primary example of this. 122 | 123 | Node.js currently has **reference** documentation, but because of the lack of 124 | **topic** and **guide** documentation, it ends up having to repeat itself a 125 | lot. Sometimes the lack of a dedicated place for this kind of documentation 126 | means that reference docs will attempt to include guides or topic docs inline — 127 | this usually doesn't end up working well in the long run. 128 | 129 | The Docs WG has identified and created a few guides already, some of which are 130 | the subject of the [first](#one-pulling-guides-into-nodejsnode) task. 131 | *However*, we need help filling in the gaps — both in identifying needed docs, 132 | as well as in executing on them. 133 | 134 | It's important to note that this documentation applies as much to topics 135 | *internal* to the project as it does to our externally facing API — we need 136 | guides and overviews for the architecture of Node, as well as how to 137 | collaborate on the project. 138 | 139 | ##### Subtasks 140 | 141 | Want to pitch in? Look here! If someone's already working on the task, see 142 | if they need help. 143 | 144 | * Overviews: 145 | * "Encoding", to be used by the Buffer and FS docs. 146 | * "Blocking vs. non-blocking." — **@jrit** [#77](https://github.com/nodejs/docs/issues/77) 147 | * Syscall documentation, to be used primarily by FS, but throughout the codebase. 148 | * Internal: Node.js Architecture — **@eljefedelrodeodeljefe** [#71](https://github.com/nodejs/docs/issues/71) 149 | * Internal: Initialization process — **@thealphanerd** [#73](https://github.com/nodejs/docs/issues/73) 150 | * Internal: Signals 151 | * Internal: Docs WG Process — **@chrisdickinson** 152 | * Guides: 153 | * Internal: New Collaborator guide — **@nodejs/inclusivity**, **@ashleygwilliams** [nodejs/inclusivity#96](https://github.com/nodejs/inclusivity/issues/96) 154 | * Internal: Move "cutting releases" into these guides — **@thealphanerd** [#75](https://github.com/nodejs/docs/issues/75) 155 | * Streams: For Authors 156 | * Streams: For Consumers — **@bengl** 157 | * Walkthroughs for each module 158 | * Reference: 159 | * Glossary of terms, to be used by all docs. 160 | * Streams: remove guide content from API doc once guides have been written. 161 | * Streams: Descriptive spec — **@nodejs/streams** [nodejs/readable-stream#181](https://github.com/nodejs/readable-stream/issues/181) 162 | * Identifying other docs to create 163 | 164 | #### :three: Improving API Metadata 165 | 166 | One of the most common requests we've received is that the API docs start 167 | including relevant version information alongside methods. This information 168 | should include the version the API was introduced in, when it was last changed, 169 | and when it was deprecated, if applicable. Second to that, we've received 170 | requests to automatically link types of parameters to the appropriate MDN or 171 | Node.js documentation sections, and note what (if any) errors an API will 172 | generate, and how it will propagate them. 173 | 174 | This points to the need to standardize tooling around this metadata, and then 175 | execute against that tooling. 176 | 177 | This task should track the work being done in task #1 — that is to say, this 178 | metadata should be tracked by remark plugins in as much as is possible. 179 | 180 | ##### Subtasks 181 | 182 | * Per-section YAML — **@qard**, **@tflanagan** [nodejs/node#3867](https://github.com/nodejs/node/pull/3867) 183 | * Noting 'version introduced' on each API — **@tflanagan** 184 | * Ideally this should link to the CHANGELOG for that release. 185 | * Standardizing API method signature documentation 186 | * Type annotation — **@fansworld-claudio** [nodejs/node#4741](https://github.com/nodejs/node/pull/4741) 187 | * (This will have to be brought into the Remark work as well.) 188 | * Error generation 189 | * Automatically linking `syscall(2)`-format terms to the appropriate docs. 190 | * Allow authors to pick a simpler anchor for headings in addition to the 191 | autogenerated anchor. 192 | 193 | ### Notably Missing 194 | 195 | There are a few things notably missing from this list — this is not because 196 | they are not important to us, but because we are primarily constrained by time 197 | and the size of the content we are working within. Foremost among the missing 198 | pieces is an internationalization strategy. This task cannot be approached 199 | lightly, and will likely include touching *all* of the docs in a single PR. 200 | While we welcome discussion on how to approach this issue, we will not be 201 | executing on it until after March 2016. Likewise, search is an extant issue 202 | that we do not have the resources to work on at present. 203 | 204 | ### Pitching In 205 | 206 | If you would like to help out with the Docs, you can: 207 | 208 | * Find a subtask above and raise your hand on the associated issue or create 209 | an issue on the [docs issue tracker][docs-tracker]. 210 | * Raise your hand [here][weekly-review] to help with the weekly docs review 211 | load. 212 | 213 | [docs-tracker]: https://github.com/nodejs/docs/issues/new 214 | [goals]: https://github.com/nodejs/node/blob/master/WORKING_GROUPS.md#documentation 215 | [guide-docs]: https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides 216 | [issue-roadmap]: https://github.com/nodejs/docs/issues/59 217 | [ref-doctool]: https://github.com/nodejs/node/tree/master/tools/doc 218 | [ref-getting-started]: ./GETTING-STARTED.md 219 | [ref-remark]: https://www.npmjs.com/package/remark 220 | [repo-nodejs]: https://github.com/nodejs/node 221 | [weekly-review]: https://github.com/nodejs/docs/issues/69 222 | [wg-ctc]: https://github.com/nodejs/node 223 | [wg-inclusivity]: https://github.com/nodejs/inclusivity/ 224 | [wg-website]: https://github.com/nodejs/nodejs.org/ 225 | -------------------------------------------------------------------------------- /assets/code-examples/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /assets/css/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /assets/img/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /assets/js/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /meetings/2015-08-18.md: -------------------------------------------------------------------------------- 1 | # Node.js Documentation WG Meeting Aug 2015-08-18 2 | 3 | YouTube recording: 4 | 5 | ## Attendance 6 | 7 | * Drew (gh: @drewfish) 8 | * Bryan English (gh/tw: @bengl) 9 | * Sean Ouimet (gh: @snostorm, tw: @skepticsean) 10 | * Stephen Belanger (gh: @qard, tw: @stephenbelanger) 11 | * Chris Dickinson (gh: @chrisdickinson, tw: @isntitvacant) 12 | * Sam Roberts (gh: @sam-github) 13 | 14 | ## Agenda 15 | 16 | 17 | * Intros 18 | * Governance 19 | * https://github.com/nodejs/docs/pull/14 20 | * Build/Website Integration 21 | * Loose notes from discussions at summit https://docs.google.com/document/d/1ajbjZZMUtSKAJ5Ha9qcyZboewo8Tq67s8oTARc1-Vy0/edit?usp=sharing 22 | * Moving API Docs from nodejs/node to nodejs/docs 23 | * [Issue on node core](https://github.com/nodejs/node/issues/2366) 24 | * Overview of [open PRs](https://github.com/nodejs/docs/pulls) 25 | * [#8 building-from-src.md](https://github.com/nodejs/docs/pull/8) 26 | * [#14 GOVERNANCE.md](https://github.com/nodejs/docs/pull/14) 27 | * [#24 topics/async](https://github.com/nodejs/docs/pull/24) 28 | 29 | 30 | ## Minutes 31 | 32 | ### Governance 33 | https://github.com/nodejs/docs/pull/14 34 | * governance PR open 35 | * merge that, or otherwise solidify process 36 | * PR 37 | * chris 38 | * boilerplate-y 39 | * steps on the toes of other .mds we have 40 | * would like to have a governance.md 41 | * drew 42 | * liked what we have, PR seemed a bit heavy 43 | * perhaps move what we have (getting-started.md) to governance.md 44 | * perhaps merge in that parts of the PR that we like 45 | * chris 46 | * PR points to where the members are listed, and code of conduct 47 | * leans towards the getting-started.md 48 | * maybe start with a stripped-down governance.md 49 | * action 50 | * update PR with a smaller scope 51 | * volunteers? bryan 52 | 53 | 54 | 55 | 56 | ### Build/Website Integration 57 | * talked about a bunch at node summit 58 | * website WG uses metalsmith 59 | * leaning towards mdast 60 | * sean: website WG 61 | * trying to make publishing process streamlined for needs of many working groups 62 | * manage different i18ns 63 | * don't want to duplicate a bunch of tooling 64 | * coherence for users 65 | * website repo/WG -- build tooling 66 | * docs WG can help evolve tooling 67 | * website group/repo -- styling, etc 68 | * docs WG -- lean, content oriented 69 | * website WG -- eventually split off tooling 70 | * chris: ask from docs WG 71 | * move towards mdast 72 | * linting, link checking, etc 73 | * adding "introduced in" etc tags 74 | * metalsmith plugin to use mdast 75 | * could website WG move to mdast? 76 | * sean: 77 | * yeah, mdast should be fine, has other nice benefits 78 | * website WG is pretty early, can make changes 79 | * chris: 80 | * getting docs WG content into the website repo 81 | * PRs temporarily until there's a better solution? 82 | * sean: 83 | * website isn't published yet 84 | * coming weeks 85 | * cowboy days, process doesn't matter too much 86 | * … so maybe don't need the PRs approach yet 87 | 88 | 89 | 90 | 91 | ### Moving API Docs from `nodejs/node` to `nodejs/docs` 92 | 93 | 94 | [Issue on node core](https://github.com/nodejs/node/issues/2366) 95 | * chris: 96 | * talk on node repo about where API docs should live 97 | * sanguine on it living in the docs repo 98 | * core is pushing for API docs in node repo 99 | * if we say "we'll write docs for you" that's a massive commitment for docs WG 100 | * sam: 101 | * not sure we can sell that 102 | * chris: 103 | * yeah, just a hunch 104 | * sam: 105 | * a code author (i.e. node repo contributor) might have a better idea of how to write the docs 106 | * if the code is hard to write docs for, that's an indication that perhaps the code/approach might need some review 107 | * in favor of API docs in node repo 108 | * chris: 109 | * not super fixed on either approach 110 | * sam: 111 | * for core author, easier to work on a single repo 112 | * a bunch of stuff in api docs isn't api docs: 113 | * errors 114 | * debugger page 115 | * addon page 116 | * examples 117 | * lots of stuff in current API docs which could be removed/moved 118 | * sean: 119 | * “remove examples from api docs” was met with broad agreement at node summit meeting 120 | * api docs in node repo very bare-bones 121 | * if examples are needed can do cross linking 122 | * stephen: 123 | * core repo should just contain API reference, examples/guides should move to docs repo 124 | * "needs-docs" tag for changes which need a more comprehensive guide, but shouldn't block 125 | * chris: 126 | * worried about API docs separate from docs repo: assumes a world where the API docs don't link back to guides and tutorials 127 | * will need to be linking between API docs and guides/tutorials 128 | * … and such all docs need to be versioned together 129 | * suggest: pull API docs into docs repo, also leave in node repo, mass PR into node repo. merge conflict of english language is painful 130 | * sam: 131 | * "leave the API docs in the core" doesn't include infrastructure, just the markdown in core 132 | * treat it as source, which would go into docs site build processes 133 | * would be happen for API docs in core repo to include references which would only make sense once those docs are published (AKA "up references" or "side references") 134 | * drew: 135 | * had assumed that as well 136 | * sam: 137 | * does that address concerns about linking? 138 | * chris: 139 | * concerned about the artificial distance between the docs repo and api docs in core repo would get bigger 140 | * linking API docs to/from topics or guides gets tricky 141 | * sam: 142 | * api docs 143 | * poorly organized 144 | * no overarching framework 145 | * no guides/priciples for writing API docs 146 | * apis aren't currently sufficiently documented in reference form 147 | * API changes made w/out API docs being updated 148 | * make it easier/mandatory for code PRs to include the needed API docs changes 149 | * make it easy for docs group to make over-arching docs 150 | * bryan: 151 | * one concern 152 | * two separate contribution processes: one for docs repo and one for core repo (which has API docs) 153 | * if well documented (how to contribute) in our contributing guide, then that might be OK 154 | * sean: 155 | * maintaining one set of API docs which represent the "edge" case of node.js 156 | * single version of docs which presents docs for all versions of node 157 | * this might make some things, especially crosslinking, easier (or less problematic) 158 | * editors of the guides, including API, are writing docs to the current version 159 | * someone using an older version are aware of deprecations etc 160 | * also gives visibility of how node.js has evolved 161 | * drew: 162 | * had assumed that 163 | * sam: 164 | * makes api in core easier or harder? 165 | * sean: 166 | * perhaps harder -- do we maintain old APIs in core repo master? 167 | * sam: 168 | * perhaps easier -- single source of truth 169 | * chris: 170 | * when linking, difficulties figuring out which version to link to 171 | * do we want to make a lot of sweeping changes to API docs? 172 | * involves make a lot of changes in node repo 173 | * not sure if contribution process to node repo will work for sweeping changes to docs 174 | * … might stall docs, or produce worse docs 175 | * sean: 176 | * argument for splitting the repo: i18n 177 | * already are i18n groups who are already doing wild west processes for translating API docs 178 | * no good place to link to 179 | * no good place to contribute to 180 | * approach of new website 181 | * base is english folder 182 | * separate folders per language 183 | * all language PRs are equal 184 | * sentiment to do something similar on docs repo 185 | * … do those start landing in core? get's noisy for core, bundling trickiness 186 | * consistent i18n of docs will make things easier for the docs team 187 | * chris: 188 | * unified method for i18n process? 189 | * sean: 190 | * yes 191 | * if english API docs are the only thing in a different place, might be weird 192 | * or sending translated docs to node repo, might be weird 193 | * sam: 194 | * might not be weird 195 | * other i18n groups might catch up 196 | * … unless API docs start in another language 197 | * sean: 198 | * i18n translators will need to clone and track two repos 199 | * sam: 200 | * a big change to rip all the API docs out, to a docs site which hasn't produced docs yet 201 | * separate API docs approach, doesn't have to be that way forever 202 | * once docs WG is pushing out higher quality docs site, we could then take on ownership of API docs 203 | * sean: 204 | * let's get a proof of concept going with all the other guides, tooling, etc 205 | * until then we're not ready to pull API docs out of core 206 | * drew: 207 | * until then, docs WG could help figure out how to write API docs in a consistent way 208 | * sam: 209 | * … to provide templates, markup, tools, etc 210 | * chris: 211 | * chris's read: too scary of a change to rip out API docs until we've produced a website 212 | * proposes: slurping API docs, making our changes, then PR back our changes to core 213 | * once we have a site, propose an official move 214 | * not super optimistic about making changes of API docs while in core repo. core repo has a different pace, different set of goals 215 | * time check 216 | * punting discussion of open PRs 217 | * sean: 218 | * make a round of sweeping change, then push back to core? 219 | * … or keep cherry picking? 220 | * need a proposal 221 | * chris: 222 | * make a round of sweeping changes, and PR it 223 | * if API changes, examine and pull them in 224 | * push/pull model, two sources 225 | * temporary until we prove we can build a website 226 | * bryan: 227 | * instead of asking for a removal of API docs dir, get ownership of API docs dir [in node repo]? 228 | * chris: 229 | * we can ask for that 230 | * distributed colab network in node repo, so getting the word out is difficult and takes time 231 | * sam: 232 | * we effectively already own it, since we can already "LGTM" a docs PR 233 | * one difficulty with docs PR in node is just getting someone to _review_ the docs, so having a docs WG around to do that would help 234 | * bryan: 235 | * clarification: ownership of docs directory in node core 236 | * sean: 237 | * do some really quick house cleaning -- remove non-API docs from node repo 238 | * assets, tooling, etc (non-contentious stuff) 239 | * chris: 240 | * one minute left 241 | * a couple of different avenues 242 | * chris will be talking at TSC meeting about this (most likely), will present the different strategies 243 | * will create a new issue for transition strategy 244 | * wrap up 245 | * unsure when next meeting 246 | 247 | 248 | 249 | ### Overview of open PRs. 250 | punted, due to length of API docs discussion 251 | 252 | #### [#8 building-from-src.md](https://github.com/nodejs/docs/pull/8) 253 | 254 | 255 | #### [#14 GOVERNANCE.md](https://github.com/nodejs/docs/pull/14) 256 | * already discussed in `Governance` topic 257 | 258 | 259 | #### [#24 topics/async](https://github.com/nodejs/docs/pull/24) 260 | -------------------------------------------------------------------------------- /src/guides/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /src/guides/anatomy-of-an-http-transaction.md: -------------------------------------------------------------------------------- 1 | # Anatomy of an HTTP Transaction 2 | 3 | The purpose of this guide is to impart a solid understanding of the process of 4 | Node.js HTTP handling. We'll assume that you know, in a general sense, how HTTP 5 | requests work, regardless of language or programming environment. We'll also 6 | assume a bit of familiarity with Node.js [`EventEmitters`][] and [`Streams`][]. 7 | If you're not quite familiar with them, it's worth taking a quick read through 8 | the API docs for each of those. 9 | 10 | ## Create the Server 11 | 12 | Any node web server application will at some point have to create a web server 13 | object. This is done by using [`createServer`][]. 14 | 15 | ```javascript 16 | var http = require('http'); 17 | 18 | var server = http.createServer(function(request, response) { 19 | // magic happens here! 20 | }); 21 | ``` 22 | 23 | The function that's passed in to [`createServer`][] is called once for every 24 | HTTP request that's made against that server, so it's called the request 25 | handler. In fact, the [`Server`][] object returned by [`createServer`][] is an 26 | [`EventEmitter`][], and what we have here is just shorthand for creating a 27 | `server` object and then adding the listener later. 28 | 29 | ```javascript 30 | var server = http.createServer(); 31 | server.on('request', function(request, response) { 32 | // the same kind of magic happens here! 33 | }); 34 | ``` 35 | 36 | When an HTTP request hits the server, node calls the request handler function 37 | with a few handy objects for dealing with the transaction, `request` and 38 | `response`. We'll get to those shortly. 39 | 40 | In order to actually serve requests, the [`listen`][] method needs to be called 41 | on the `server` object. In most cases, all you'll need to pass to `listen` is 42 | the port number you want the server to listen on. There are some other options 43 | too, so consult the [API reference][]. 44 | 45 | ## Method, URL and Headers 46 | 47 | When handling a request, the first thing you'll probably want to do is look at 48 | the method and URL, so that appropriate actions can be taken. Node makes this 49 | relatively painless by putting handy properties onto the `request` object. 50 | 51 | ```javascript 52 | var method = request.method; 53 | var url = request.url; 54 | ``` 55 | > **Note:** The `request` object is an instance of [`IncomingMessage`][]. 56 | 57 | The `method` here will always be a normal HTTP method/verb. The `url` is the 58 | full URL without the server, protocol or port. For a typical URL, this means 59 | everything after and including the third forward slash. 60 | 61 | Headers are also not far away. They're in their own object on `request` called 62 | `headers`. 63 | 64 | ```javascript 65 | var headers = request.headers; 66 | var userAgent = headers['user-agent']; 67 | ``` 68 | 69 | It's important to note here that all headers are represented in lower-case only, 70 | regardless of how the client actually sent them. This simplifies the task of 71 | parsing headers for whatever purpose. 72 | 73 | If some headers are repeated, then their values are overwritten or joined 74 | together as comma-separated stings, depending on the header. In some cases, this 75 | can be problematic, so [`rawHeaders`][] is also available. 76 | 77 | ## Request Body 78 | 79 | When receiving a `POST` or `PUT` request, the request body might be important to 80 | your application. Getting at the body data is a little more involved than 81 | accessing request headers. The `request` object that's passed in to a handler 82 | implements the [`ReadableStream`][] interface. This stream can be listened to or 83 | piped elsewhere just like any other stream. We can grab the data right out of 84 | the stream by listening to the stream's `'data'` and `'end'` events. 85 | 86 | The chunk emitted in each `'data'` event is a [`Buffer`][]. If you know it's 87 | going to be string data, the best thing to do is collect the data in an array, 88 | then at the `'end'`, concatenate and stringify it. 89 | 90 | ```javascript 91 | var body = []; 92 | request.on('data', function(chunk) { 93 | body.push(chunk); 94 | }).on('end', function() { 95 | body = Buffer.concat(body).toString(); 96 | // at this point, `body` has the entire request body stored in it as a string 97 | }); 98 | ``` 99 | 100 | > **Note:** This may seem a tad tedious, and in many cases, it is. Luckily, 101 | there are modules like [`concat-stream`][] and [`body`][] on [`npm`][] which can 102 | help hide away some of this logic. It's important to have a good understanding 103 | of what's going on before going down that road, and that's why you're here! 104 | 105 | ## A Quick Thing About Errors 106 | 107 | Since the `request` object is a [`ReadableStream`][], it's also an 108 | [`EventEmitter`][] and behaves like one when an error happens. 109 | 110 | An error in the `request` stream presents itself by emitting an `'error'` event 111 | on the stream. **If you don't have a listener for that event, the error will be 112 | *thrown*, which could crash your Node.js program.** You should therefore add an 113 | `'error'` listener on your request streams, even if you just log it and 114 | continue on your way. (Though it's probably best to send some kind of HTTP error 115 | response. More on that later.) 116 | 117 | ```javascript 118 | request.on('error', function(err) { 119 | // This prints the error message and stack trace to `stderr`. 120 | console.error(err.stack); 121 | }); 122 | ``` 123 | 124 | There are other ways of [handling these errors][] such as using [`domains`][] or 125 | other abstractions and tools, but always be aware that errors can and do happen, 126 | and you're going to have to deal with them. 127 | 128 | ## What We've Got so Far 129 | 130 | At this point, we've covered creating a server, and grabbing the method, URL, 131 | headers and body out of requests. When we put that all together, it might look 132 | something like this: 133 | 134 | ```javascript 135 | var http = require('http'); 136 | 137 | http.createServer(function(request, response) { 138 | var headers = request.headers; 139 | var method = request.method; 140 | var url = request.url; 141 | var body = []; 142 | request.on('error', function(err) { 143 | console.error(err); 144 | }).on('data', function(chunk) { 145 | body.push(chunk); 146 | }).on('end', function() { 147 | body = Buffer.concat(body).toString(); 148 | // At this point, we have the headers, method, url and body, and can now 149 | // do whatever we need to in order to respond to this request. 150 | }); 151 | }).listen(8080); // Activates this server, listening on port 8080. 152 | ``` 153 | 154 | If we run this example, we'll be able to *receive* requests, but not *respond* 155 | to them. In fact, if you hit this example in a web browser, your request would 156 | time out, as nothing is being sent back to the client. 157 | 158 | So far we haven't touched on the `response` object at all, which is an instance 159 | of [`ServerResponse`][], which is a [`WritableStream`][]. It contains many 160 | useful methods for sending data back to the client. We'll cover that next. 161 | 162 | ## HTTP Status Code 163 | 164 | If you don't bother setting it, the HTTP status code on a response will always 165 | be 200. Of course, not every HTTP response warrants this, and at some point 166 | you'll definitely want to send a different status code. To do that, you can set 167 | the `statusCode` property. 168 | 169 | ```javascript 170 | response.statusCode = 404; // Tell the client that the resource wasn't found. 171 | ``` 172 | 173 | There are some other shortcuts to this, as we'll see soon. 174 | 175 | ## Setting Response Headers 176 | 177 | Headers are set through a convenient method called [`setHeader`][]. 178 | 179 | ```javascript 180 | response.setHeader('Content-Type', 'application/json'); 181 | response.setHeader('X-Powered-By', 'bacon'); 182 | ``` 183 | 184 | When setting the headers on a response, the case is insensitive on their names. 185 | If you set a header repeatedly, the last value you set is the value that gets 186 | sent. 187 | 188 | ## Explicitly Sending Header Data 189 | 190 | The methods of setting the headers and status code that we've already discussed 191 | assume that you're using "implicit headers". This means you're counting on node 192 | to send the headers for you at the correct time before you start sending body 193 | data. 194 | 195 | If you want, you can *explicitly* write the headers to the response stream. 196 | To do this, there's a method called [`writeHead`][], which writes the status 197 | code and the headers to the stream. 198 | 199 | ```javascript 200 | response.writeHead(200, { 201 | 'Content-Type': 'application/json', 202 | 'X-Powered-By': 'bacon' 203 | }); 204 | ``` 205 | 206 | Once you've set the headers (either implicitly or explicitly), you're ready to 207 | start sending response data. 208 | 209 | ## Sending Response Body 210 | 211 | Since the `response` object is a [`WritableStream`][], writing a response body 212 | out to the client is just a matter of using the usual stream methods. 213 | 214 | ```javascript 215 | response.write(''); 216 | response.write(''); 217 | response.write('

Hello, World!

'); 218 | response.write(''); 219 | response.write(''); 220 | response.end(); 221 | ``` 222 | 223 | The `end` function on streams can also take in some optional data to send as the 224 | last bit of data on the stream, so we can simplify the example above as follows. 225 | 226 | ```javascript 227 | response.end('

Hello, World!

'); 228 | ``` 229 | 230 | > **Note:** It's important to set the status and headers *before* you start 231 | writing chunks of data to the body. This makes sense, since headers come before 232 | the body in HTTP responses. 233 | 234 | ## Another Quick Thing About Errors 235 | 236 | The `response` stream can also emit `'error'` events, and at some point you're 237 | going to have to deal with that as well. All of the advice or `request` stream 238 | errors still applies here. 239 | 240 | ## Put It All Together 241 | 242 | Now that we've learned about making HTTP responses, let's put it all together. 243 | Building on the earlier example, we're going to make a server that sends back 244 | all of the data that was send to us by the user. We'll format that data as JSON 245 | using `JSON.stringify`. 246 | 247 | ```javascript 248 | 249 | var http = require('http'); 250 | 251 | http.createServer(function(request, response) { 252 | var headers = request.headers; 253 | var method = request.method; 254 | var url = request.url; 255 | var body = []; 256 | request.on('error', function(err) { 257 | console.error(err); 258 | }).on('data', function(chunk) { 259 | body.push(chunk); 260 | }).on('end', function() { 261 | body = Buffer.concat(body).toString(); 262 | // BEGINNING OF NEW STUFF 263 | 264 | response.on('error', function(err) { 265 | console.error(err); 266 | }); 267 | 268 | response.statusCode = 200; 269 | response.setHeader('Content-Type', 'application/json'); 270 | // Note: the 2 lines above could be replaced with this next one: 271 | // response.writeHead(200, {'Content-Type': 'application/json'}) 272 | 273 | var responseBody = { 274 | headers: headers, 275 | method: method, 276 | url: url, 277 | body: body 278 | }; 279 | 280 | response.write(JSON.stringify(responseBody)); 281 | response.end(); 282 | // Note: the 2 lines above could be replaced with this next one: 283 | // response.end(JSON.stringify(responseBody)) 284 | 285 | // END OF NEW STUFF 286 | }); 287 | }).listen(8080); 288 | ``` 289 | 290 | ## Echo Server Example 291 | 292 | Let's simplify the previous example to make a simple echo server, which just 293 | sends whatever data is received in the request right back in the response. All 294 | we need to do is grab the data from the request stream and write that data to 295 | the response stream, similar to what we did previously. 296 | 297 | ```javascript 298 | var http = require('http'); 299 | 300 | http.createServer(function(request, response) { 301 | var body = []; 302 | request.on('data', function(chunk) { 303 | body.push(chunk); 304 | }).on('end', function() { 305 | body = Buffer.concat(body).toString(); 306 | response.end(body); 307 | }); 308 | }).listen(8080); 309 | ``` 310 | 311 | Now let's tweak this. We want to only send an echo under the following 312 | conditions: 313 | 314 | * The request method is GET. 315 | * The URL is `/echo`. 316 | 317 | In any other case, we want to simply respond with a 404. 318 | 319 | ```javascript 320 | var http = require('http'); 321 | 322 | http.createServer(function(request, response) { 323 | if (request.method === 'GET' && request.url === '/echo') { 324 | var body = []; 325 | request.on('data', function(chunk) { 326 | body.push(chunk); 327 | }).on('end', function() { 328 | body = Buffer.concat(body).toString(); 329 | response.end(body); 330 | }) 331 | } else { 332 | response.statusCode = 404; 333 | response.end(); 334 | } 335 | }).listen(8080); 336 | ``` 337 | 338 | > **Note:** By checking the URL in this way, we're doing a form of "routing". 339 | Other forms of routing can be as simple as `switch` statements or as complex as 340 | whole frameworks like [`express`][]. If you're looking for something that does 341 | routing and nothing else, try [`router`][]. 342 | 343 | Great! Now let's take a stab at simplifying this. Remember, the `request` object 344 | is a [`ReadableStream`][] and the `response` object is a [`WritableStream`][]. 345 | That means we can use [`pipe`][] to direct data from one to the other. That's 346 | exactly what we want for an echo server! 347 | 348 | ```javascript 349 | var http = require('http'); 350 | 351 | http.createServer(function(request, response) { 352 | if (request.method === 'GET' && request.url === '/echo') { 353 | request.pipe(response); 354 | } else { 355 | response.statusCode = 404; 356 | response.end(); 357 | } 358 | }).listen(8080); 359 | ``` 360 | 361 | Yay streams! 362 | 363 | We're not quite done yet though. As mentioned multiple times in this guide, 364 | errors can and do happen, and we need to deal with them. 365 | 366 | To handle errors on the request stream, we'll log the error to `stderr` and send 367 | a 400 status code to indicate a `Bad Request`. In a real-world application, 368 | though, we'd want inspect the error to figure out what the correct status code 369 | and message would be. As usual with errors, you should consult the 370 | [`Error` documentation][]. 371 | 372 | On the response, we'll just log the error to `stdout`. 373 | 374 | ```javascript 375 | var http = require('http'); 376 | 377 | http.createServer(function(request, response) { 378 | request.on('error', function(err) { 379 | console.error(err); 380 | response.statusCode = 400; 381 | response.end(); 382 | }); 383 | response.on('error', function(err) { 384 | console.error(err); 385 | }); 386 | if (request.method === 'GET' && request.url === '/echo') { 387 | request.pipe(response); 388 | } else { 389 | response.statusCode = 404; 390 | response.end(); 391 | } 392 | }).listen(8080); 393 | ``` 394 | 395 | We've now covered most of the basics of handling HTTP requests. At this point, 396 | you should be able to: 397 | 398 | * Instantiate an HTTP server with a request handler function, and have it listen 399 | on a port. 400 | * Get headers, URL, method and body data from `request` objects. 401 | * Make routing decisions based on URL and/or other data in `request` objects. 402 | * Send headers, HTTP status codes and body data via `response` objects. 403 | * Pipe data from `request` objects and to `response` objects. 404 | * Handle stream errors in both the `request` and `response` streams. 405 | 406 | From these basics, Node.js HTTP servers for many typical use cases can be 407 | constructed. There are plenty of other things these APIs provide, so be sure to 408 | read through the API docs for [`EventEmitters`][], [`Streams`][], and [`HTTP`][]. 409 | 410 | 411 | 412 | [`EventEmitters`]: https://iojs.org/api/events.html 413 | [`Streams`]: https://iojs.org/api/stream.html 414 | [`createServer`]: https://iojs.org/api/http.html#http_http_createserver_requestlistener 415 | [`Server`]: https://iojs.org/api/http.html#http_class_http_server 416 | [`listen`]: https://iojs.org/api/http.html#http_server_listen_port_hostname_backlog_callback 417 | [API reference]: https://iojs.org/api/http.html 418 | [`IncomingMessage`]: https://iojs.org/api/http.html#http_http_incomingmessage 419 | [`ReadableStream`]: https://iojs.org/api/stream.html#stream_class_stream_readable 420 | [`rawHeaders`]: https://iojs.org/api/http.html#http_message_rawheaders 421 | [`Buffer`]: https://iojs.org/api/buffer.html 422 | [`concat-stream`]: https://www.npmjs.com/package/concat-stream 423 | [`body`]: https://www.npmjs.com/package/body 424 | [`npm`]: https://www.npmjs.com 425 | [`EventEmitter`]: https://iojs.org/api/events.html#events_class_events_eventemitter 426 | [handling these errors]: https://iojs.org/api/errors.html 427 | [`domains`]: https://iojs.org/api/domain.html 428 | [`ServerResponse`]: https://iojs.org/api/http.html#http_class_http_serverresponse 429 | [`setHeader`]: https://iojs.org/api/http.html#http_response_setheader_name_value 430 | [`WritableStream`]: https://iojs.org/api/stream.html#stream_class_stream_writable 431 | [`writeHead`]: https://iojs.org/api/http.html#http_response_writehead_statuscode_statusmessage_headers 432 | [`express`]: https://www.npmjs.com/package/express 433 | [`router`]: https://www.npmjs.com/package/router 434 | [`pipe`]: https://iojs.org/api/stream.html#stream_readable_pipe_destination_options 435 | [`Error` documentation]: https://iojs.org/api/errors.html 436 | [`HTTP`]: https://iojs.org/api/http.html 437 | -------------------------------------------------------------------------------- /src/meta/reference/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /src/meta/topics/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /src/meta/topics/dependencies.md: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | 3 | There are several dependencies that Node.js relies on to work the way it does. 4 | 5 | - [Libraries](#Libraries) 6 | - [V8](#V8) 7 | - [libuv](#libuv) 8 | - [http-parser](#http-parser) 9 | - [c-ares](#c-ares) 10 | - [OpenSSL](#OpenSSL) 11 | - [zlib](#zlib) 12 | - [Tools](#Tools) 13 | - [npm](#npm) 14 | - [gyp](#gyp) 15 | - [gtest](#gtest) 16 | 17 | ## Libraries 18 | 19 | ### V8 20 | 21 | The V8 library provides Node.js with a JavaScript engine, which Node.js 22 | controls via the V8 C++ API. V8 is maintained by Google, for use in Chrome. 23 | 24 | - [Documentation](https://v8docs.nodesource.com/) 25 | 26 | ### libuv 27 | 28 | Another important dependency is libuv, a C library that is used to abstract 29 | non-blocking I/O operations to a consistent interface across all supported 30 | platforms. It provides mechanisms to handle file system, DNS, network, child 31 | processes, pipes, signal handling, polling and streaming. It also includes a 32 | thread pool for offloading work for some things that can't be done 33 | asynchronously at the operating system level. 34 | 35 | - [Documentation](http://docs.libuv.org/) 36 | 37 | ### http-parser 38 | 39 | HTTP parsing is handled by a lightweight C library called http-parser. It is 40 | designed to not make any syscalls or allocations, so it has a very small 41 | per-request memory footprint. 42 | 43 | - [Documentation](https://github.com/joyent/http-parser/) 44 | 45 | ### c-ares 46 | 47 | For some asynchronous DNS requests, Node.js uses a C library called c-ares. 48 | It is exposed through the DNS module in JavaScript as the resolve() family of 49 | functions. The lookup() function, which is what the rest of core uses, makes 50 | use of threaded getaddrinfo(3) calls in libuv. The reason for this is that 51 | c-ares supports /etc/hosts, /etc/resolv.conf and /etc/svc.conf, but not things 52 | like mDNS. 53 | 54 | - [Documentation](http://c-ares.haxx.se/docs.html) 55 | 56 | ### OpenSSL 57 | 58 | OpenSSL is used extensively in both the `tls` and `crypto` modules. It provides 59 | battle-tested implementations of many cryptographic functions that the modern 60 | web relies on for security. 61 | 62 | - [Documentation](https://www.openssl.org/docs/) 63 | 64 | ### zlib 65 | 66 | For fast compression and decompression, Node.js relies on the industry-standard 67 | zlib library, also known for its use in gzip and libpng. Node.js uses zlib to 68 | create sync, async and streaming compression and decompression interfaces. 69 | 70 | - [Documentation](http://www.zlib.net/manual.html) 71 | 72 | ## Tools 73 | 74 | ### npm 75 | 76 | Node.js is all about modularity, and with that comes the need for a quality 77 | package manager; for this purpose, npm was made. With npm comes the largest 78 | selection of community-created packages of any programming ecosystem, 79 | which makes building Node.js apps quick and easy. 80 | 81 | - [Documentation](https://docs.npmjs.com/) 82 | 83 | ### gyp 84 | 85 | The build system is handled by gyp, a python-based project generator copied 86 | from V8. It can generate project files for use with build systems across many 87 | platforms. Node.js requires a build system because large parts of it — and its 88 | dependencies — are written in languages that require compilation. 89 | 90 | - [Documentation](https://chromium.googlesource.com/external/gyp/+/master/docs/UserDocumentation.md) 91 | 92 | ### gtest 93 | 94 | Native code can be tested using gtest, which is taken from Chromium. It allows 95 | testing C/C++ without needing an existing node executable to bootstrap from. 96 | 97 | - [Documentation](https://code.google.com/p/googletest/wiki/V1_7_Documentation) 98 | -------------------------------------------------------------------------------- /src/reference/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /src/topics/.gitkeep: -------------------------------------------------------------------------------- 1 | --------------------------------------------------------------------------------