docs: update built-in components

Author: rakannimer

src/docs/documentation/general/built-in-components.mdx

@@ -7,16 +7,20 @@ menu: General
 
 # Built-in components
 
-Docz has built-in components that help you to document your things. Using the power of components and AST to parse and generate data for them, we can do a lot of things,
-like render your components, create tables with contents, custom getters by traversing your file, etc. The sky is the limit here!
+Docz has built-in components that help you document your code. 
+
+Using the power of components and their parsed ASTs ([Abstract Syntax Trees](https://en.wikipedia.org/wiki/Abstract_syntax_tree)) 
+we can do a lot of things, like render your components, create tables with content describing them, generate documentation from your code, define custom getters by traversing your files and many other things.
+The sky is the limit here!
 
 ## Playground Component
 
-With the `<Playground>` component, you can render your component inside a playground and see the code used:
+With the `<Playground>` component, you can render your component inside a live-editable playground and directly see the output of the code used:
 
 ```markdown
 ---
 name: Button
+route: /
 ---
 
 import { Playground } from 'docz'
@@ -32,24 +36,29 @@ import { Button } from './Button'
 </Playground>
 ```
 
-![](https://cdn-std.dprcdn.net/files/acc_649651/hrRpoR)
+![Page showing two buttons and their code inside an editable playground](https://cdn-std.dprcdn.net/files/acc_649651/hrRpoR)
+
+As you can see, `<Playground>` renders your components, and right below them displays an editable version of the code used.
+This can be very useful to test and develop your components in a good environment while also documenting them. 
 
-As you see, `<Playground>` rendered your component in a blank state, and right below, displayed the code used to.
-This can be very useful to test and develop your components in a good environment while you document it. The code below the component is also editable and the changes you make to that code will reflect live in the component above!
+Note that you can edit the code below the components from your browser and see the changes you make be reflected live above it!
 
 ## Component Props
 
-Maybe the most important thing when you write a component is know which properties it has.
-However, keeping a good properties documentation of your component can be boring, because you need to write
-the props specification and maintain the original props definition. And we know that to keep both in sync can be troublesome!
+One of the most important things when documenting a component is to know which props it expects.
+
+However, keeping a good properties documentation for your component can be difficult and error-prone, because you need to write
+the props specification and maintain the original props definition separately. This makes it hard to keep them both in sync !
 
-Docz offers a solution to this problem called the `<Props>`. It's a simple component that automatically gets the
-props definition of your component and display them in a cool component.
-Simple like that and works nicely with Flow and Typescript.
+Docz offers a solution to this problem called the `<Props>` component. It's a component that automatically gets the
+props definitions of your component and displays them in a neat table along with their default value and an optional description.
+
+In addition to supporting parsing `prop-types` in JS code, it works nicely with Flow and Typescript.
 
 ```markdown
 ---
 name: Button
+route: /
 ---
 
 import { Playground, Props } from 'docz'
@@ -67,15 +76,17 @@ import { Button } from './'
 </Playground>
 ```
 
-The button that will display the props must have some annotation on the props. For non flow or typescript users this can be achieved with [`prop-types`](https://www.npmjs.com/package/prop-types)
+The Button component must have some annotation describing its props. 
+
+For non flow or typescript users this can be achieved with [`prop-types`](https://www.npmjs.com/package/prop-types)
 
 ```jsx
 import React from 'react'
 import t from 'prop-types'
 
 const Button = ({ children, kind }) => {
-  // Do something nice with the kind prop, like add a class with it
-  return <button>{children}</button>
+  // We use the kind prop to determine the button's class
+  return <button className={kind}>{children}</button>
 }
 
 Button.propTypes = {
@@ -90,9 +101,9 @@ Button.defaultProps = {
 export Button
 ```
 
-If you have used `prop-types` you should now have a list of properties in a nicely formatted table:
+If you have used `prop-types` like described above, you should see a list of properties in a nicely formatted table:
 
-![](https://cdn-std.dprcdn.net/files/acc_649651/KEm5mH)
+![Table describing Button's props ](https://cdn-std.dprcdn.net/files/acc_649651/KEm5mH)
 
 The same can be achieved in typescript by adding comments to the props interface of your component:
 
@@ -107,4 +118,6 @@ interface ButtonProps {
 }
 ```
 
-You can read more in depth about our built-in components on [**Components API**](/docs/components-api). If you are more interested in learning more about the MDX-pages you could head on to [**Document Settings**](/docs/document-settings)
+You can read a more in-depth guide about our built-in components in [**Components API**](/docs/components-api). 
+
+And if you prefer to dive deeper into MDX document settings you can head over to [**Document Settings**](/docs/document-settings)