Updating documentation

FAQ.md

@@ -0,0 +1,43 @@
+# [Office UI Fabric React FAQ](http://dev.office.com/fabric)
+
+## *Q. What is Office UI Fabric React?*
+
+Fabric React is a responsive, mobile-first, open-source collection of robust components designed to make it quick and simple for you to create web experiences using the `Office Design Language`.
+
+## *Q. Who uses Office UI Fabric React?*
+
+React components from Office UI Fabric React are used by many teams accross O365 and Microsoft for building their experiences. Some examples are Sharepoint, OneDrive, Outlook, VisualStudio Online, ...
+
+These components are also used by third party developers buiding extensiblity components using the SharePoint Framework.
+
+## *Q. How do I get started with Office UI Fabric React?*
+
+Start with our [README](./README.md) document.
+
+## *Q. Where is the official website located?*
+
+http://dev.office.com/fabric
+
+## *Q. Can I contribute to Office UI Fabric React?*
+
+Office UI Fabric React is an open-source distributed project. Lots of developers from inside and outside Microsoft contribute to this project. We highly encourage contributions. There is a core team that works hard to stay on top of the issues and pull requests.
+
+## *Q. Why should I contribute?*
+
+Office UI Fabric React is an open-source distributed project. If you are building a new app inside O365 or Microsoft, this project will potentially save you lots of time, resources and headaches. We encourage all developers who use Fabric React to return a small amount to the community. If you notice bugs, we encourage you to not only open an issue on it but also help fix it. If you have a component that you believe others should use, feel motivated and encouraged to contribute that component back to the community. Sharing is caring. Many developers contribute outside their primary job responsibilities. Additionally, there is plenty to learn. We use a lot of best practices used in the industry. Learning those can  help you in your career.
+
+## *Q. How do I communicate with a Fabric React core team member?*
+
+We have a very active community both outside and inside Microsoft. Please use the Microsoft [Teams channel](https://teams.microsoft.com/l/channel/19%3a73a5dbc26c9a4d8d91264611995bbdbb%40thread.skype/Fabric%2520Design?groupId=ffe264f2-14d0-48b5-9384-64f808b81294&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47) for communication from within Microsoft. And a [GitHub issue](https://github.com/OfficeDev/office-ui-fabric-react/issues) from outside Microsoft. We triage these issues at least once a week.
+
+## *Q. How do I contribute to Office UI Fabric React?*
+
+Start by reading our [Contributing](./ghdocs/Contributing/Contributing.md) document. Please point out any missing or incorrect details.
+
+## *Q. Can I become a part of the Fabric core team?*
+
+Yes, you totally can. You will need to help out with reviewing pull requests and triaging and fixing issues. For now, only Microsoft employees can be a part of the core team. We are looking into changing that policy to allow non-Microsoft folks to be a part of the core team.
+
+## *Q. My pull request has been hanging for a long time. What do I do?*
+
+We are very proactive and work hard to keep the outstanding pull request count low. But if your pull request is non-trivial and stuck for a long time, please feel free to tag the pull request that it has been hanging for long and you need help.

README.md

@@ -51,7 +51,7 @@ ReactDOM.render(
 
 ## Browser support
 
-Fabric React supports many commonly used browsers. See the [browser support doc](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/ghdocs/BROWSERSUPPORT.md) for more information.
+Fabric React supports many commonly used browsers. See the [browser support doc](./ghdocs/Testing/BrowserSupport.md) for more information.
 
 ## Server-side rendering
 
@@ -116,7 +116,7 @@ responsiveLib.setResponsiveMode(responsiveLib.ResponsiveMode.large);
 You'll also want to mock out requiring `.scss` files.
 In Jest:
 
-```javascript
+```js
   moduleNameMapper: {
     // jest-style-mock.js should just contain module.exports = {};
     '\\.(scss)$': path.resolve(__dirname, 'jest-style-mock.js'),
@@ -125,15 +125,15 @@ In Jest:
 
 ## Advanced usage
 
-For advanced usage including info about module vs. path-based imports, using an AMD bundler like Require, and deployment features, see our [advanced documentation](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/ghdocs/ADVANCED.md).
+For advanced usage including info about module vs. path-based imports, using an AMD bundler like Require, and deployment features, see our [advanced documentation](./ghdocs/BestPractices/Advanced.md).
 
-## Contribute to Fabric React
+## Contribute to Office UI Fabric React
 
-Please take a look at our [contribution guidelines](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/ghdocs/CONTRIBUTING.md) for more info.
+Please take a look at our [contribution guidelines](./ghdocs/Contributing/Contributing.md) for more info. Also read [Contribute Bug fixes](./ghdocs/Contributing/BugFixes.md) and [Contribute New component](./ghdocs/Contributing/NewComponent.md).
 
 ## Building the repo
 
-Before you get started, **make sure you have [node.js](https://nodejs.org/) and [git](https://git-scm.com/) installed.**
+Before you get started, **make sure you have read the [Git branch setup instrucions](./ghdocs/Contributing/Setup.md)**
 
 To view the documentation including examples, contracts, component status, and to add functionality or fix issues locally, you can:
 
@@ -149,7 +149,7 @@ To build individual packages within the `packages/*/` folders, you can use `npm
 
 ## Testing
 
-For testing see our [testing documentation](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/ghdocs/TESTING.md).
+For testing see our [testing documentation](./ghdocs/BestPractices/Testing.md).
 
 ## Advanced building tips
 

ghdocs/Accessibility.md → ghdocs/BestPractices/Accessibility.md

@@ -10,28 +10,20 @@ Default color choices should conform to contrast requirements as laid out in [WC
 
 We best support high contrast in Internet Explorer 11 and Microsoft Edge. Mozilla FireFox is also supported to the extent possible barring technical constraints. Read on for more details.
 
-The recommended approach here is to use the correct elements to match your scenario.
-Sometimes, you'll have to use a similar, but not exactly right, element.
-For example, when making a custom checkbox, you can wrap it in a `<button>` element.
-This will cause it to pick up the correct colors in all three supported browsers.
+The recommended approach here is to use the semantically correct elements to match your scenario. For example, use a `<button>` element for a Button and not a `<div>`. Sometimes, you'll have to use a similar, but not exactly right, element. For example, when making a custom checkbox, you can wrap it in a `<button>` element. This will cause it to pick up the correct colors in all three supported browsers.
 
 As a backup approach, high contrast colors can be manually applied in CSS.
-These colors should ONLY be from the [System Colors](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#System_Colors) palette.
-The logic on when to apply these colors can vary, from using media queries (see below) or using code to detect when high contrast is on.
+These colors should ONLY be from the [System Colors](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#System_Colors) palette. The logic on when to apply these colors can vary, from using media queries (see below) or using code to detect when high contrast is on.
 
-The last approach is to use media queries with `-ms-high-contrast` to scope styles to high contrast.
-Since this only work in Internet Explorer and Microsoft Edge, it is not recommended as a general strategy.
-We use this only where necessary, for complex scenarios such as multiselect.
+The last approach is to use media queries with `-ms-high-contrast` to scope styles to high contrast. Since this only work in Internet Explorer and Microsoft Edge, it is not recommended as a general strategy. We use this only where necessary, for complex scenarios such as multiselect.
 
 Note that background images can disappear in high contrast mode. Any icons or images that are required for functionality must not be background images.
 
-In high contrast mode, color should not be the only means of conveying feedback.
-A transparent border or outline will appear in high contrast mode, a useful way of denoting focus without affecting non-high contrast visual design.
+In high contrast mode, color should not be the only means of conveying feedback. A transparent border or outline will appear in high contrast mode, a useful way of denoting focus without affecting non-high contrast visual design.
 
 ## Screen Reader
 
-Follow recommended guidelines using [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) to insure the best support for screen readers.
-Where necessary, add in extra text only visible to the screen reader for descriptions and directions, by positioning it off screen.
+Follow recommended guidelines using [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) to insure the best support for screen readers. Where necessary, add in extra text only visible to the screen reader for descriptions and directions, by positioning it off screen.
 
 Our primary support scenario is Microsoft Edge with Windows Narrator.