[new docs] initial draft of glossary docs #8199

mrscobbler · 2016-11-03T22:45:15Z

Would love some feedback on these terms -- let me know if there are other terms that should be added.

gaearon · 2016-11-17T14:32:59Z

Hey, sorry about the long time for review.
I think it would really help to add links to the corresponding docs.

For example, the JSX paragraph can have something like "To get familiar with JSX, read [Intro to JSX]. You can also read [JSX in Depth] to learn more about it."

Same for other topics.

mrscobbler · 2016-11-17T15:14:39Z

Ok! What about the list of terms? Is there anything I should add?

gaearon · 2016-11-17T16:15:21Z

docs/docs/reference-glossary.md

+React components are small, resuable pieces of code that return a React element to be rendered to the page. The simplest version of React component is a plain JavaScript function that returns a React element. Components can be broken down into distinct pieces of functionality and used within other components. Components must return a single root element (wrapped in a `div` or other similar container). Component names should also always start with a capital letter (`<Wrapper/>` **not** `<wrapper/>`)
+
+
+### `props`


Let's say just "Props" in the header. Same for "Children" and "State".

gaearon · 2016-11-17T16:17:00Z

Looks good for the first pass. I think it would be great to add "bundler", "compiler", etc—all the terms people might see on other doc pages. Think somebody who never wrote any JavaScript: which words would they be confused about as they read through our docs?

mrscobbler · 2016-11-17T16:34:35Z

Ok! Gives me a good excuse to thoroughly read through the docs! :)

… of github.com:facebook/react

mrscobbler · 2017-01-27T02:04:14Z

So sorry for the delay! I've added more terms and included links to relevant documentation where necessary. Check it out @gaearon when you get a chance.

aweary

Looking really good, added some feedback!

aweary · 2017-01-27T02:42:08Z

docs/docs/reference-glossary.md

+ ES6 AKA ES2015 is the current version of the ECMAScript Language Specification standard, which the JavaScript language is an implementation of. It includes many additions to the previous versions such as: arrow functions, classes, template literals, and `let` and `const` statements. 
+
+## Compilers/Transpilers
+A JavaScript compiler (or transpiler) takes JavaScript code, transforms it and returns JavaScript code in a different format. The most common use case is to take ES2015/ES6 syntax and transform it into syntax that browsers are capable of interpreting. Babel is the compiler used with React. 


Maybe it's too pedantic to matter, but technically only transpilers, a subset of compilers, take source code and return source code. Maybe we can clarify this, something like:

A JavaScript transpiler is a compiler that takes JavaScript code, transforms it, and returns JavaScript code in a different format.

Ok yeah -- I'm still a little fuzzy on the difference between transpilers and compilers -- some of the articles I read about it said the words were interchangeable.

Yeah its kind of a tricky topic. A compiler is a general term for any program that takes source code in, and outputs some other representation of that code. Usually, compilers will compile code from a source language (like JavaScript) to a lower level target language (like machine code).

A transpiler is a special kind of compiler that takes in one type of source code and outputs another type of source code. So babel is a transpiler since it takes in JavaScript and outputs JavaScript

We were trying to avoid saying "transpiler" in new docs because it confuses everyone. Let's just always say "compiler" and ignore the "transpiler" term. Even Babel docs don't use it.

aweary · 2017-01-27T02:44:23Z

docs/docs/reference-glossary.md

+A JavaScript compiler (or transpiler) takes JavaScript code, transforms it and returns JavaScript code in a different format. The most common use case is to take ES2015/ES6 syntax and transform it into syntax that browsers are capable of interpreting. Babel is the compiler used with React. 
+
+## Bundlers
+Bundlers put all of your JavaScript code & dependency into one "bundle", usually into one file. Some bundlers commonly used in React applications include: Webpack & Browserify 


Lets just use "and" instead of "&" throughout the doc.

Also, missing period at the end.

aweary · 2017-01-27T02:45:00Z

docs/docs/reference-glossary.md

+Bundlers put all of your JavaScript code & dependency into one "bundle", usually into one file. Some bundlers commonly used in React applications include: Webpack & Browserify 
+
+## Package Manager 
+Package managers are tools that allow you to manage dependencies in your project. npm & Yarn are two package managers commonly used in React applications


Missing period at the end.

aweary · 2017-01-27T02:46:55Z

docs/docs/reference-glossary.md

+CDN stands for Content Delivery Network. CDNs deliver cached, static content from a network of servers across the globe. 
+
+## JSX
+JSX is a syntax extension to JavaScript. It is similar to a template language. When JSX gets compiled, the result is JavaScript objects called "elements". To get a basic introduction to JSX [see the docs here](https://facebook.github.io/react/docs/introducing-jsx.html) and find a more in-depth tutorial on JSX [here](https://facebook.github.io/react/docs/jsx-in-depth.html)


When JSX gets compiled, the result is JavaScript objects called "elements".

JSX doesn't get compiled directly to objects. It is typically compiled to function calls that return those objects. In React its compiled to React.createElement calls.

Should the "intro to JSX" documentation be modified? In this section: https://facebook.github.io/react/docs/introducing-jsx.html#jsx-is-an-expression-too it says "After compilation, JSX expressions become regular JavaScript objects."

For the glossary, I can change the phrasing to say something like "JSX gets compiled to React.createElement() calls which return plain JavaScript objects called 'React elements'." <-- Does that feel like a better description? I was trying to keep the definitions simple and refer people to the actual documentation if they wanted to dig a little deeper.

Yeah we should probably update that section as its misleading. You can see here that JSX gets compiled to React.createElement calls that return objects called "elements".

Does that feel like a better description?

That definitely sounds better 👍

aweary · 2017-01-27T02:47:30Z

docs/docs/reference-glossary.md

+## JSX
+JSX is a syntax extension to JavaScript. It is similar to a template language. When JSX gets compiled, the result is JavaScript objects called "elements". To get a basic introduction to JSX [see the docs here](https://facebook.github.io/react/docs/introducing-jsx.html) and find a more in-depth tutorial on JSX [here](https://facebook.github.io/react/docs/jsx-in-depth.html)
+
+React DOM uses camelCase property naming convention instead of HTML attribute names.


It might be helpful to clarify that we use the JavaScript API naming conventions specifically.

aweary · 2017-01-27T03:10:19Z

docs/docs/reference-glossary.md

+For example, class becomes className in JSX, and tabindex becomes tabIndex.
+
+## [Elements](https://facebook.github.io/react/docs/rendering-elements.html)
+React elements are the building blocks of React applications. One might confuse elements with a more widely known concept of "components". Elements are what components are "made of".An element describes what you want to see on the screen. React elements are immutable.


Missing space after third sentence.

aweary · 2017-01-27T03:47:33Z

docs/docs/reference-glossary.md

+`props` are inputs to a React component. They are data passed down from a parent component to a child component. `props` are readonly -- they should not be modified in any way. All React components must act like pure functions with respect to their `props`.
+
+### `this.props.children`
+`this.props.children` is available on every component. It contains the content between the opening and closing tags of a component. For example:


For function components, it would just be props.children, since you access it on the passed parameter and not this

aweary · 2017-01-27T03:48:00Z

docs/docs/reference-glossary.md

+ A "key" is a special string attribute you need to include when creating lists of elements. Keys help React identify which items have changed, are added, or are removed. Keys should be given to the elements inside an array to give the elements a stable identity.
+
+## [Refs](https://facebook.github.io/react/docs/refs-and-the-dom.html)
+React supports a special attribute that you can attach to any component. When the ref attribute is used on an HTML element, the ref callback receives the underlying DOM element as its argument. This allows you to have direct access to the DOM element


Refs can be functions or strings (string refs are pretty-much-legacy but still allowed). Also, missing a period at the end.

aweary · 2017-01-27T03:50:35Z

docs/docs/reference-glossary.md

+* With JSX you pass a function as the event handler, rather than a string.
+
+
+## Reconciliation


Let's link to the reconcilliation doc page here: https://facebook.github.io/react/docs/reconciliation.html

gaearon · 2017-01-27T14:46:43Z

@aweary Thanks for jumping on this!

aweary · 2017-01-27T15:21:55Z

docs/docs/reference-glossary.md

+The string `Hello world!` is available in `this.props.children` in the `Welcome` component.
+
+### [`state`](https://facebook.github.io/react/docs/state-and-lifecycle.html#adding-local-state-to-a-class)
+A component's `state` is a snapshot of the data contained in a component. `props` and `state` are different: `state` is user-defined, `props` are received from a parent component.


A component's state is a snapshot of the data contained in a component.

I'm worried this might sound misleading; someone might think state is a periodical snapshot of the props passed in or something. Maybe rephrase to something like:

State is a way for components to manage data that is private and fully controlled by that component.

That's also closer to what we say in the linked docs page.

state is user-defined, props are received from a parent component.

props are technically user-defined too, just defined in another component 😄 It may be more accurate to say:

state is owned and controlled by the component that created it. props are received from a parent component.

aweary · 2017-01-27T15:24:10Z

docs/docs/reference-glossary.md

+React has two different approaches to dealing with form inputs. An input form element whose value is controlled by React is called a *controlled component*. An *uncontrolled component* is an input that is just like any normal input we would use outside of React. When a user inputs data into a form field (an input box, dropdown, etc) the updated information is reflected. 
+
+## [Keys](https://facebook.github.io/react/docs/lists-and-keys.html) 
+ A "key" is a special string attribute you need to include when creating lists of elements. Keys help React identify which items have changed, are added, or are removed. Keys should be given to the elements inside an array to give the elements a stable identity.


A "key" is a special string attribute you need to include when creating lists of elements.

I don't think there's any specific restriction that says a key has to be a string. It's the most common thing to use, but you could also use numbers, or even objects.

kkemple · 2017-03-20T19:14:31Z

@mrscobbler is this still being actively developed?

mrscobbler · 2017-03-20T21:33:04Z

yes, I've made some of the changes but haven't had a chance to push them to github. Is this something you're interested in collaborating on?

kkemple · 2017-03-20T23:55:56Z

yeah! would love to help out! 😄

mrscobbler · 2017-03-31T05:34:14Z

@aweary made the changes you requested! Take a look. @kkemple if you think there's anything else we should add make a pull request! /cc @gaearon

bvaughn · 2017-10-06T17:23:03Z

Thank you for submitting this PR! 😄

Unfortunately the documentation and source code for reactjs.org has been moved to a different repository: https://github.com/reactjs/reactjs.org

I realize this PR is old and there may no longer be interest in seeing it merged. If there is, please open a new PR there. Sorry for the inconvenience!

(For more backstory on why we moved to a new repo, see issue #11075)

initial draft of glossary

bb070a7

facebook-github-bot added the GH Review: review-needed label Nov 3, 2016

mrscobbler mentioned this pull request Nov 3, 2016

[New Docs] Wanted Guides #8060

Closed

13 tasks

facebook-github-bot added the CLA Signed label Nov 3, 2016

mrscobbler changed the title ~~initial draft of glossary docs~~ [new docs] initial draft of glossary docs Nov 8, 2016

gaearon self-assigned this Nov 8, 2016

zpao added the Component: Documentation & Website label Nov 17, 2016

gaearon reviewed Nov 17, 2016

View reviewed changes

mrscobbler added 6 commits December 6, 2016 08:45

more changes to glossary

d10f43b

Merge branch 'master' of github.com:mrscobbler/react; branch 'master'…

92bc870

… of github.com:facebook/react

Merge branch 'master' of github.com:facebook/react

86a467c

Merge branch 'master' of github.com:facebook/react

cffaaab

Changes and additions to react glossary docs

d8e3b4d

Adding links to glossary terms

d82957a

aweary suggested changes Jan 27, 2017

View reviewed changes

aweary reviewed Jan 27, 2017

View reviewed changes

sebmarkbage removed the GH Review: review-needed label Mar 1, 2017

Incorporating feedback on glossary terms

f155f37

gaearon mentioned this pull request Sep 19, 2017

[New Docs] Set Up Localization Effort #8063

Closed

bvaughn closed this Oct 6, 2017

mrscobbler mentioned this pull request Oct 13, 2017

Porting over glossary content from old repository reactjs/react.dev#153

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[new docs] initial draft of glossary docs #8199

[new docs] initial draft of glossary docs #8199

mrscobbler commented Nov 3, 2016

gaearon commented Nov 17, 2016

mrscobbler commented Nov 17, 2016

gaearon Nov 17, 2016

gaearon commented Nov 17, 2016

mrscobbler commented Nov 17, 2016

mrscobbler commented Jan 27, 2017

aweary left a comment

aweary Jan 27, 2017

mrscobbler Jan 27, 2017

aweary Jan 27, 2017 •

edited

Loading

gaearon Jan 27, 2017

aweary Jan 27, 2017

aweary Jan 27, 2017

aweary Jan 27, 2017

aweary Jan 27, 2017

mrscobbler Jan 27, 2017 •

edited

Loading

aweary Jan 27, 2017

aweary Jan 27, 2017

aweary Jan 27, 2017

aweary Jan 27, 2017

aweary Jan 27, 2017

aweary Jan 27, 2017

gaearon commented Jan 27, 2017

aweary Jan 27, 2017

aweary Jan 27, 2017

kkemple commented Mar 20, 2017

mrscobbler commented Mar 20, 2017

kkemple commented Mar 20, 2017

mrscobbler commented Mar 31, 2017

bvaughn commented Oct 6, 2017

		React components are small, resuable pieces of code that return a React element to be rendered to the page. The simplest version of React component is a plain JavaScript function that returns a React element. Components can be broken down into distinct pieces of functionality and used within other components. Components must return a single root element (wrapped in a `div` or other similar container). Component names should also always start with a capital letter (`<Wrapper/>` not `<wrapper/>`)


		### `props`

		* With JSX you pass a function as the event handler, rather than a string.


		## Reconciliation

[new docs] initial draft of glossary docs #8199

[new docs] initial draft of glossary docs #8199

Conversation

mrscobbler commented Nov 3, 2016

gaearon commented Nov 17, 2016

mrscobbler commented Nov 17, 2016

Choose a reason for hiding this comment

gaearon commented Nov 17, 2016

mrscobbler commented Nov 17, 2016

mrscobbler commented Jan 27, 2017

aweary left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aweary Jan 27, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mrscobbler Jan 27, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gaearon commented Jan 27, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kkemple commented Mar 20, 2017

mrscobbler commented Mar 20, 2017

kkemple commented Mar 20, 2017

mrscobbler commented Mar 31, 2017

bvaughn commented Oct 6, 2017

aweary Jan 27, 2017 •

edited

Loading

mrscobbler Jan 27, 2017 •

edited

Loading