Updating documentation by manishgarg1 · Pull Request #4490 · microsoft/fluentui

manishgarg1 · 2018-04-09T04:33:29Z

Description of changes

Some document restructuring to set it up for future improvements.

dzearing

The organization looks fine to me. I assume you haven't changed a lot of the content. I can't really tell from the diff.

Jahnp

This looks great to me! Thanks for the improvements, @manishgarg1 --looking forward to future additions. I left a few small comments for spelling/grammar, but otherwise this looks good to go.

Jahnp · 2018-04-10T03:16:19Z

FAQ.md

+
+## *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, ...


Small nits for spelling/grammar: SharePoint, Visual Studio team Services #Resolved

Jahnp · 2018-04-10T03:16:42Z

FAQ.md

+
+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.


Spelling nit: buiding -> building #Resolved

Jahnp · 2018-04-10T03:17:17Z

FAQ.md

+
+## *Q. Where is the official website located?*
+
+http://dev.office.com/fabric


https://developer.microsoft.com/fabric (could also use uifabric.io) #Resolved

Jahnp · 2018-04-10T03:18:11Z

FAQ.md

+
+## *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.


👍👍👍 #Resolved

Big thanx for reviewing @Jahnp. #Resolved

Jahnp · 2018-04-10T03:21:28Z

ghdocs/BestPractices/Testing.md

 Our tests are built using [Jest](https://facebook.github.io/jest/). This allows us to run tests in a node environment, and simulates the browser using jsdom.

-For snapshot testing, we use `react-test-renderer` and Jest apis.
+For snapshot testing, we use `react-test-renderer` and `Jest apis`.


Tiny tiny nit: Should this be Jest APIs? #Resolved

@Jahnp, for some of these docs, I am just moving them at this point. Will then work on them individually once this PR is merged.

In reply to: 180287991 [](ancestors = 180287991)

Gotcha, makes sense, rock on. Was seeing other changes in here as a part of that (adding the quotes) so I assumed you were doing small content changes too. #Resolved

Very little here and there where the meaning of the content won't change.

In reply to: 180502872 [](ancestors = 180502872)

aditima · 2018-04-09T23:09:58Z

ghdocs/Contributing/ChangeFiles.md

+
+- Addition or removal of functionality in a non backward compatible way.
+
+- A new component should qualify as a **major** change.


Why should a new component be a major change? I would intuitively think it would be a minor as long as it's not affecting any existing one.,.. #Resolved

aditima · 2018-04-09T23:21:03Z

ghdocs/Contributing/NewComponent.md

+#### Fundamental components
+Fundamental components are the official React representation of our [Adobe XD Toolkit](https://static2.sharepointonline.com/files/fabric/fabric-website/files/officeuifabric_v4.0.0.zip) and receive higher priority in respect to stabilization, bug fixes, accessibility and general design resourcing. Components __cannot__ be immediately added as a Fundamental type component as it will need a period of stabilization and API review. All components should always start off as Experimental. A good portion of the Fundamental components are currently integrated within some of our major products such as OneDrive, SharePoint and Outlook. Fundamental components are developed in the office-ui-fabric-react project in the `<root of project>/packages/office-ui-fabric-react` folder.
+
+### Start coding your component


David and I were talking about this once earlier, and at least for internal submissions, we thought having a design review before the dev begins coding is useful. We should encourage people to try to break their component into reusable building blocks, and try to reuse existing building blocks (or variants) whenever possible to keep the overall code volume small. The design review can help achieve this before going too far ahead into coding.

Now, doing this for public github submissions is likely not feasible. Also, we do not want to be the bottle-neck here. But I clearly see the point where the Fabric Core team can be in a better position to do this composition than any random developer. #Resolved

aditima · 2018-04-09T23:22:30Z

ghdocs/Contributing/NewComponent.md

+export * from './ExcitingNewComponent.types';
+```
+
+### Unit tests and screener tests


David had a nice list of horizontals to satisfy before we promote a component from Experimental to Fundamental. We should capture this somewhere...

Work with a designer (Angela or Ben) to get their buyoff and make sure it fits our branding.

Documentation (a documentation page with examples, that are consistent and readable)

Tests (Visual Regression tests, Snapshot tests, and functional unit tests)

Accessible correct aria labeling, keyboardable, renders in RTL correctly, and supports high contrast)

Theme-able (no hard coded colors, uses semantic color slots)

Consistent API interface (has componentRef, className, supports injecting data- attributes etc.)
#Resolved

aditima · 2018-04-09T23:35:04Z

ghdocs/README.md

@@ -1,153 +0,0 @@
-## Overview


are we moving this elsewhere? #Resolved

manishgarg1 · 2018-04-10T17:12:57Z

ghdocs/Contributing/NewComponent.md

+  * In this example the component will be called `ExcitingNewComponent`.
+3. Create a `ExcitingNewComponent.types.ts` file that will contain an interface for your component props
+
+  * @todo: review


todo [](start = 5, length = 4)

Resolve before merging #Resolved

dzearing · 2018-04-10T17:36:53Z

ghdocs/Contributing/NewComponent.md

+  * Import ExcitingNewComponent
+    * `import { ExcitingNewComponent } from './ExcitingNewComponent'`;
+    * Note: This class and file don't exist yet but they will during step 4 of this small tutorial.
+  * Create an empty interface `IExcitingNewComponent`


Create an empty interface (which may contain the public imperative API surface, such as focus().) #Resolved

dzearing · 2018-04-10T17:37:59Z

ghdocs/Contributing/NewComponent.md

+export interface IExcitingNewComponent {
+}
+
+export interface IExcitingNewComponentProps extends React.Props<ExcitingNewComponent> {


the ts file should import the types from the file. #Resolved

dzearing · 2018-04-10T17:38:39Z

ghdocs/Contributing/NewComponent.md

+  /**
+  * All props for your component are to be defined here.
+  */
+  componentRef?: (component: IExcitingNewComponent) => void;


this should be moved up into the .types description, explaining this is how customers should access the imperative API surface (through componentRef) #Resolved

Manish Garg added 3 commits April 2, 2018 15:44

Initial stab at documentation cleanup

0c442f4

Doc updates first iteration

46a544c

Some more updates

c81fed6

manishgarg1 requested review from aditima and dzearing April 9, 2018 04:33

dzearing changed the title ~~Manishga/doc updates3~~ Updating documentation Apr 9, 2018

dzearing approved these changes Apr 9, 2018

View reviewed changes

Manish Garg added 3 commits April 9, 2018 15:04

Added FAQ

86a6df9

Fixed some links

82e8457

Minor cleanup

7c519e0

Jahnp approved these changes Apr 10, 2018

View reviewed changes

more code review comments

91d57c5

aditima reviewed Apr 10, 2018

View reviewed changes

manishgarg1 commented Apr 10, 2018

View reviewed changes

dzearing reviewed Apr 10, 2018

View reviewed changes

aditima approved these changes Apr 10, 2018

View reviewed changes

Manish Garg added 3 commits April 10, 2018 11:53

SampleApp document

ec6f708

Fixed SampleApp link

8c41829

Some final cleanup

3b3d9c2

manishgarg1 merged commit 565e903 into microsoft:master Apr 10, 2018

microsoft locked as resolved and limited conversation to collaborators Aug 31, 2019


		## 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, ...


		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. Where is the official website located?

		http://dev.office.com/fabric


		## 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.


		- Addition or removal of functionality in a non backward compatible way.

		- A new component should qualify as a major change. No newline at end of file

Conversation

manishgarg1 commented Apr 9, 2018

Description of changes

Uh oh!

dzearing left a comment

Choose a reason for hiding this comment

Uh oh!

Jahnp left a comment

Choose a reason for hiding this comment

Uh oh!

Jahnp Apr 10, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jahnp Apr 10, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jahnp Apr 10, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jahnp Apr 10, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manishgarg1 Apr 10, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jahnp Apr 10, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manishgarg1 Apr 10, 2018

Choose a reason for hiding this comment

Uh oh!

Jahnp Apr 10, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manishgarg1 Apr 10, 2018

Choose a reason for hiding this comment

Uh oh!

aditima Apr 9, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aditima Apr 9, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aditima Apr 9, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aditima Apr 9, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manishgarg1 Apr 10, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dzearing Apr 10, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dzearing Apr 10, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dzearing Apr 10, 2018 • edited by manishgarg1 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Jahnp Apr 10, 2018 •

edited by manishgarg1

Loading

Jahnp Apr 10, 2018 •

edited by manishgarg1

Loading

Jahnp Apr 10, 2018 •

edited by manishgarg1

Loading

Jahnp Apr 10, 2018 •

edited by manishgarg1

Loading

manishgarg1 Apr 10, 2018 •

edited

Loading

Jahnp Apr 10, 2018 •

edited by manishgarg1

Loading

Jahnp Apr 10, 2018 •

edited by manishgarg1

Loading

aditima Apr 9, 2018 •

edited by manishgarg1

Loading

aditima Apr 9, 2018 •

edited by manishgarg1

Loading

aditima Apr 9, 2018 •

edited by manishgarg1

Loading

aditima Apr 9, 2018 •

edited by manishgarg1

Loading

manishgarg1 Apr 10, 2018 •

edited

Loading

dzearing Apr 10, 2018 •

edited by manishgarg1

Loading

dzearing Apr 10, 2018 •

edited by manishgarg1

Loading

dzearing Apr 10, 2018 •

edited by manishgarg1

Loading