[RFC: Docs] Add DirectManipluation guide to explain setNativeProps

[brentvatne]

If someone could read this over and give me some feedback it would be much appreciated.

Addresses #1390

[ide]

setNativeProps is best used for continuous animations, to avoid the overhead of rendering the component hierarchy and reconciling many views. I believe we want to discourage it from an API perspective since it is imperative and stores state in the native layer (DOM, UIView, etc.)

[brentvatne]

👍 should have mentioned the continuous animations use case

[brentvatne]

also should be sure to emphasize more that this shouldn't be something that you use frequently outside of that use case

[ccheever]

Random nitpick:
might change "(avoid a render pass, useful with continuous animations)"
to "(to avoid a render pass, which is useful with continuous animations)" or something like that.

At a higher level, I would change the framing of "Only use this if you really need to" to more of a "When to use this and when not to and why not". I generally agree with @ide that performance is the main reason to use it, and that you are trading off complexity of implementation for small -- but sometimes critically important -- gains in UI smoothness, etc.

Overall, I think this is awesome! I think that this will go along way to making bits of React Native less mysterious and get more people building good stuff on it.

[brentvatne]

Great point @ccheever - updated accordingly

[brentvatne]

I'm happy with this now, thanks so much for the help @ide@ccheever ❤️