Difficulties and suggestions for React-Native docs

RNResponse.md

Difficulties and suggestions around a newbie using React-Native 0.20

This is a response to a chap on twitter asking about possible improvements to prevent having to 'treasure hunt' knowledge to make React-Native work.

I am primarily a full stack web guy, with some hardware and app experience from overseeing "Zombies, Run". What did and didn't work for me may not be applicable to others!

Documentation shortcomings

The official docs are brief and have a number of shortcomings that required me to fill in gaps in knowledge, either via experimentation or through trawling internet forums.

Complex classes handled briefly

One powerful but opaque component I've been using is the PanResponder. It's great! But also very thinly documented in some ways. There is one example given, but given the huge range of complexity that class could undergo, basics of understanding are often skipped over. For example, from the documentation I'm not sure what's inside the created pan responder, or how to access properties to bind to external needs such as dynamic styles.

onPanResponderGrant: (event, gestureState) => {
        this.state.pan.setOffset({
          x: this.state.pan.x._value,
          y: this.state.pan.y._value,
        });
        this.state.pan.setValue({x: 0, y: 0});
      },

The above is an example of a piece of code I use. It's cool to know that the offset can apparently be set. I have no idea why we're using underscore properties to access x and y. It was in someone else's codebase, and It Worked, so now it's in mine. Not an ideal transaction!

Units are magic

Style is the first place where we encounter unitless things given to height, margins etc. In web development, units are given to distinguish between px, em, rem, %, vh, wh, and others. By default, the assumption would be to think these are pixels, but I have no idea if that's true, and makes it difficult to not worry about certain elements being mis-sized on very small and large devices.

Unit ambiguity also extends elsewhere. Picking on poor PanResponder again, there is a vx and a vy component of gesture state, to tell you the current velocity of the gesture. Cool! However, I have no idea what's slow, what's fast, and if it's consistent across devices. From playing around, it seems to be something that's roughly between ±5, depending on direction and speed. 3 is a 'pretty vigorous swipe'. However I had to suss this out experimentally!

Debugging tools are non-obvious

Debugging is a huge portion of all software engineering, and occasionally something will go wrong that's hard to catch. I put a property of dz in an object that expected a dx, and the app will simply crash.

Now I know there's very cool hardware debugging tool where you can debug in chrome and pause on caught exceptions, which is great! However I don't think it's mentioned anywhere, or at least not obviously. On the suggested iOS simulator, it is also a bit of a clandestine thing to find. Simulator -> Hardware -> Shake Gesture.

Styles are just like CSS! Except not.

One might naively think they can just rock out any CSS3 mcguffin and expect it to work in React-Native, which is not true. However what does and doesn't work, and how to achieve interactions and aesthetics that I was used to was not very easy to figure out through the documentation.

Code examples are written for older versions of React (minor)

Current React-Native guides you to writing your code in the lovely newer JS syntaxes, which is then subsequently handled by Babel. Most examples in the documentation is written in the older syntax. If you have some React experience, it's trivial to convert these, but it always instils doubt about how current the docs are.

Improvement suggestions

Have a substantial example project

A number of small projects are given, but a larger project would be great as it would tackle a lot of the more complex cases that are harder to extrapolate. How do you store data between sessions? How can you make animations respond to movement? How should one structure their app when they've moved beyond one JS file and no assets?

A heavy focus on commenting that provides context would of course be great!

Have some 'translatory' examples

A couple of blogs posted examples of HTML/CSS/JS functionality that I wanted to achieve with React-Native. They wrote out the code in the manner I found easier to grok, then figured out how to write the React-Native equivalent. I would have found this extremely useful a few days back to get the basic layout and style effects going.

Documentation meat

I realise the tech is still evolving fast, but more detail on classes and a higher level context on how to compose these things together could be great. A shaky understanding of the core purpose of each component and how these interact lead to slow and, in my case, often incorrect or inelegant ways of solving problems.

Units are magic

This is an interesting topic, and I believe is not really straight forward regardless of whether or not your using React Native, UIKit directly, or Android directly. That said, I think adding a page about this in the docs would be a great addition.

More or less, my understanding is that RN uses "points" in the same way that ObjC CoreGraphics uses "points". That is, it is a single pixel if you are on a non-retina device... and if you are on a retina device, that might translate into a number of real pixels > 1, and maybe even fractional. More info/demystification on that here

My understanding is that Android uses a similar system to CoreGraphics, and this mapped out fairly well across platforms.

There is also a little-known StyleSheet.hairlineWidth property that can be used to determine what a "real" pixel is, and can be used to define thin but crisply rendered lines regardless of device.

Complex classes handled briefly

The underscore properties are usually an indication of something that is being used that is maybe intentionally being kept "private" and "undocumented" and a signal that it may change.

The way you are using setOffset here can be done instead with a call to flattenOffset for exactly this reason. This is the price we pay for a fastly-evolving framework like React Native. I suspect some of the underscore-prefixed properties may become truly private soon for performance reasons, so be mindful of that.

The PanResponder is indeed a profoundly useful class. It is hard, I think, to find truly good examples for documenting features like this. Some more effort could be put into this though, no doubt.

I'm not sure what's inside the created pan responder, or how to access properties to bind to external needs such as dynamic styles.

I'm not exactly sure what you mean by this?

If you haven't also looked at these docs they may be helpful.

There also may be better abstractions to this type of thing than the PanResponder, and some people are still exploring this. This is one such example (something that I am working on), but is still unfinished.

Styles are just like CSS! Except not.

Fair point. I think the possible style properties are fairly well documented here, however, I do think that the differences from the CSS spec should be more directly highlighted. Some things that come up a lot are:

• no support for percentage-point width/height
• no support for display: none;
• no support for transform-origin
• no support for flex-grow and flex-shrink

Debugging tools are non-obvious

FWIW, there are keyboard shortcuts (Command + D for IOS and Command - M for android) to get the developer menu up. These are also spelled out in the text of the default root component when you run react-native init my_project. I'm all for making these more visible than they are now, but I'm not sure how at this point? There is also a dedicated Debugging page in the docs.

---

This feedback was super helpful, so thanks for taking the time to write it up! The more of these issues we can fix, the better chance RN will have to succeed. There are a lot of things the RN team is working hard on right now (Note that "Improve Documentation" has 52 votes on product pains which signifies that there is indeed a problem, though it is still #10 on the list!)

Thanks for taking the time to respond to this, especially as it's the weekend! I'll clarify a couple of points.

The underscore properties are usually an indication of something that is being used that is maybe intentionally being kept "private" and "undocumented" and a signal that it may change.

I understand the conventions of underscores, hence why I was a little worried that a prominent example of how to achieve what I wanted seemed to be accessing them. I was wondering if this is 'naughty' or if using 'undocumented' things was a norm. Thanks for pointing me to flattenOffset!

I'm not sure what's inside the created pan responder, or how to access properties to bind to external needs such as dynamic styles.

I'm not exactly sure what you mean by this?

Ah, on reflection I managed to confuse myself and mixed up an instance of Animated and PanResponder. Disregard this.

CSS

This is true. I had a further mystery involving shadow* styles not working on Android, but I see it has already slipped into your known issues.

Debugging is available, right there in the side bar

You're right, I did overlook it. I think my brain just skipped across it because I didn't realise more was possible.

I think your response demonstrates that a lot of the information is available, but perhaps there might be possible improvements to discoverability and structure?

Perhaps you could expand the small 'movie list' tutorial project to briefly walk through all the key parts of RN dev? Something that covers writing some features, testing them, debugging and deploying. A good example for this sort of thing, I think, is Django's tutorials. Having talked to some of the Django foundation, I know they take their docs pretty seriously.

This would hopefully give newbies like me more of a foothold in how to approach development and what tools are available in the RN toolbox.