☂️ Website Redesign and Documentation Rewrite #929

cpojer · 2019-05-15T13:57:26Z

The content and look of the React Native website are outdated. Many of the existing guides and the overall flow of the documentation were written in 2015 and do not reflect well what it is like to build apps with React Native in 2019. When we asked what people dislike about React Native, documentation issues came up many times. We received more concrete feedback when we asked specifically.

This umbrella issue aims to outline the work necessary to update the website both with a new look and new content. While we'll handle the redesign work outside of this issue, we'd love to get your help in updating the entire documentation: if there is any item below issue that you'd love to help with, please send a Pull Request to this repo or get in touch otherwise! The best way to help right now is by updating the API docs with the actual implementations (see below) to ensure things are up-to-date for the upcoming release.

Goals

A fresh look for React Native that represents the framework in 2019.
Guides for beginners and advanced developers that are best in class.
Always up-to-date API documentation that is synced with actual code and examples.

Redesign

The redesign is currently being worked on by @orta and @tesseralis. We are excited for you all to get a look very soon!

New Guide Structure

The current structure is quite outdated. It's hard to know upfront exactly what the new flow should be like but here is the proposal for a new structure which is open for discussion:

Basics
- Setup & Getting Started
- Basics & React – this should mirror reactjs.org with a focus on RN, gently introduce RN and React, and link to reactjs.org for concepts.
- ~~Props~~ – Removed and rolled into basics, with links to reactjs.org.
- ~~State~~ – Removed and rolled into basics, with links to reactjs.org.
- Style, Height and Width – Rolled up into a new guide "Styling & Dimensions"
- Layout or "Thinking in flexbox" – Significantly expand this guide with more screenshots and possibly a live playground similar to yogalayout.com (first improvements were merged in add definition and example of how flexbox works #947).
- Handling Text Input and Handling Touches – Merge into a single "Handling User Interactions" guide
- Using a ScrollView and Using a List Views – Merge into a single guide
- ~~Networking~~ – Ideally we'll factor data fetching into the preceding guides, like populating a ScrollView content, for example.
New Guides
- Guide on "The basics of native development for Android and iOS" aimed at web developers including Xcode, Android Studio and Cocoapods and Gradle
- Include docs on RN integration into Kotlin and Swift apps.
- A list of links on app deployment for Android and iOS
- A guide on how to build a quality app (including links with information to app icons, launch screen, user interface guidelines and other polish).
Improve the guide on building native modules including how to publish it as a package.
Recommend third-party navigation libraries in the Navigation guide
All other existing guides
- Rethink all the guides beyond the basics, and improve them. This umbrella issue will be updated accordingly as we complete all the other work outlined in this issue.
- RN Accessibility Guide
???

Documentation Rewrite Tasks

~~Remove the Contributing guide from the website. Move all RN development related content into the RN GitHub repo. (@hramos)~~
~~Remove obsolete API docs (@cpojer)~~
~~Make the high level sections in the sidebar collapsible. Update Docusaurus to 1.9.0 #934 (@yangshun)~~
~~Get rid of the “Guidelines for Text (https://github.com/facebook/react-native-website/blob/master/CONTRIBUTING.md#guidelines-for-text)” (@cpojer)~~
~~Minor: Remove TimerMixins from the Timer docs, it's already gone from the code.~~
~~Minor: Get rid of packager/config.js stuff across the docs and recommend using the Metro file in the template.~~
~~Split the website up into high-level entry points for Docs (Guides) and APIs (Components and API docs). Split up Docs and API #962 @yangshun~~
Minor: AppRegistry lifecycle docs aren't good: What do you dislike about React Native? react-native-community/discussions-and-proposals#64 (comment)
A page that lists 30 of the top React Native community packages and high-quality third-party packages, like UI libraries that help people solve problems when building apps. See Add page for the Community Github Org with list of repos #884

API Docs

This is one where you can help even if you only have a few minutes. We need to update all our API docs and align them with the actual APIs in the code. For example, if you'd like to ensure consistency for the ScrollView component, it's best to go to the react-native repo and look for the ScrollView.js file. Then go through the ScrollView.md documentation in this repository and compare each prop that it accepts and update the .md file in this repo to align with what is in the code and send a Pull Request!

Guidelines

We'll prioritize improving high-impact content based on users per page per month. Right now, the pages with the most views are the guides in the basics section so we'll prioritize those.
The getting started tutorial should be a full guide from first principles to getting started, building, linking and deploying an application. It should obviate the need for a getting started guide anywhere else.
The documentation from a high-level should include all necessary details to build a performant high-quality application with React Native.
Add live demos, screenshots or find other ways to engage with the content. This could also come in the form of a real example app, although we have not had the time to build one unfortunately. If the introduction was about building a real app and was a connected step-by-step guide, that would be ideal.
If there is documentation that already exists in an official place (like Android documentation) elsewhere, link to it instead of recreating documentation. The website should be hyper focused on React Native itself. An example of this is linking to other guides on how to deploy an app to the app store, unless it requires specific knowledge because of React Native.

Finally, we are thinking of merging this repo back into the React Native repo to ensure API documentation will always stay up-to-date going forward. For now we'll keep using this repository for the purpose of this umbrella issue and we will attempt the merge later.

The text was updated successfully, but these errors were encountered:

glauberfc · 2019-05-15T14:34:06Z

Can this website be made w/ Gatsby?

cpojer · 2019-05-15T14:35:22Z

We are not considering a technical rewrite of the code. Docusauraus works fine for us at this time.

saxenanickk · 2019-05-15T14:41:54Z

Would love to contribute in this.

glauberfc · 2019-05-15T15:17:48Z

@cpojer I'm comparing ScrollView.js and ScrollView.md files and I have some questions:

Should all props inside type IOSProps be annotated w/ @platform ios. The prop below hasn't this annotation on the file:

  /**
   * When true, shows a horizontal scroll indicator.
   * The default value is true.
   */
  showsHorizontalScrollIndicator?: ?boolean,

Should the props be listed on alphabetical order?
In this part of the docs there is a link for View props indicating that this component enhance these props, but there is not a link for TouchableProps.

Do we need to create some link that show the TouchableProps too?

cpojer · 2019-05-15T15:19:22Z

@glauberfc:

Yes, IOSProps are usually ios specific.
Yes, alphabetical order is ideal.
You are right that seems to be missing. Wanna send a PR just for the touchable props?

glauberfc · 2019-05-15T15:25:18Z

You are right that seems to be missing. Wanna send a PR just for the touchable props?

@cpojer Do I need only create a file named TouchableProps.md? Is there some text explaining each of these props?

type TouchableProps = $ReadOnly<{|
  onTouchStart?: (event: PressEvent) => void,
  onTouchMove?: (event: PressEvent) => void,
  onTouchEnd?: (event: PressEvent) => void,
  onTouchCancel?: (event: PressEvent) => void,
  onTouchEndCapture?: (event: PressEvent) => void,
|}>;

dayhaysoos · 2019-05-15T16:11:09Z

I got dibs on View and Text!

yangshun · 2019-05-15T17:32:34Z

@glauberfc would love to know your reasons for moving to Gatsby 😄

glauberfc · 2019-05-15T17:44:07Z

@yangshun I thought the new React site was made with Gatsby. I think this because all sites made w/ Docusaurus are very similarly and the React website is a bit more "styled"

☂️☂️☂️☂️☂️☂️ facebook#929 ☂️☂️☂️☂️☂️☂️☂️ New APIs added: -nextFocusDown -nextFocusForward -nextFocusLeft -nextFocusUp -clickable I don't have much details on any of the `nextFocus` apis, the descriptions in the code are very vague and tell me to refer to the docs which is pretty funny because I'm adding them to the docs. Is there any easier way to figure out what new stuff has been added? I pretty much found the new APIs in the middle of View.js file, it didn't seem to have any particular order. I was hoping that new Apis would at least be at the very bottom from oldest to newest going from top to bottom.

dayhaysoos · 2019-05-15T18:05:18Z

So I made a PR for View, do my eyes deceive me or is there literally no Text.js???

orta · 2019-05-15T22:08:58Z

Make the high level sections in the sidebar collapsible.

I think this is 'just' updating docusaurus BTW

yangshun · 2019-05-15T22:15:21Z

I think this is 'just' updating docusaurus BTW

Yep there's now a siteConfig option called docsSideNavCollapsible and you can set it to true.

dayhaysoos · 2019-05-15T22:50:35Z

@yangshun @orta Sorta related to gatsby, I think it would be cool to implement MDX for handling these docs.

Every section for an API could be a component instead, should be much easier to reason about/read/contribute that way :O

yangshun · 2019-05-15T22:52:24Z

@ndejesus1227 Docusaurus 2 will support MDX. Unfortunately we haven't implementing versioning and hence cannot port React Native website to Docusaurus 2. Check out https://endiliey.com/2019/05/16/docusaurus-2-technical-preview/ for a preview.

zeabdelkhalek · 2019-05-16T01:56:10Z

Hi guys , i'd like to contribute , any contribution guide available and from where we should start?

cpojer · 2019-05-16T09:32:53Z

@yangshun any chance you could help us update Docusaurus so we can make the sidebar collapsible?

ksrini73 · 2019-05-16T10:39:08Z

I would love to contribute on this. Where should I start pl?

glauberfc · 2019-05-16T11:19:14Z

@cpojer:

On ScrollView the prop showsHorizontalScrollIndicator hasn't the @platform ios annotation, but are inside type IOSProps. Is it a missing or is it right?
scrollsToTop was changed by onScrollToTop?

cpojer · 2019-05-16T12:01:47Z

@glauberfc

Seems like it's available on Android: https://github.com/facebook/react-native/blob/faaa92bb04467f1d8cef0fe7ce309643486b7a0d/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactHorizontalScrollViewManager.java#L73
I would assume we have both, one is the boolean to toggle the behavior the other is an event that is run when scrolling to top.

glauberfc · 2019-05-16T12:04:17Z

Sorta related to gatsby, I think it would be cool to implement MDX for handling these docs.

I agree w/ you @ndejesus1227. I would like there is a way of import the component file and document it w/ MDX like in Docz. So, this will avoid us to copy and paste many times and will keep the docs updated. What do you think @cpojer @yangshun? Is there a way to do this w/ Docusaurus?

SSTPIERRE2 · 2019-05-16T14:50:25Z

Having worked with RN in it's early stages and learning from the older documentation I find this super exciting! The changes outlines here look excellent 🤘

yangshun · 2019-05-16T16:32:35Z

@cpojer will do so! I'll also enable a bunch of other useful defaults and see if you guys like it.

glauberfc · 2019-05-16T22:25:16Z

If there was something like this on Docusaurus would help a lot on the API updates. People would use a pattern to document all APIs and the JS file would be converted on a markdown file

yangshun · 2019-05-16T22:44:52Z

@glauberfc That would be possible with plugins in Docusaurus 2. I have to add a backward-compatible versioning ability to D2 before we can move RN website to D2.

dayhaysoos · 2019-05-17T14:02:44Z

I took care of View, I can't seem to find Text.js so I'm gonna pass on that one.

I'd like to call dibs on Button and FlatList! (Going for Button first)

cpojer · 2019-06-17T14:48:22Z

@ecreeth can you remove these docs via a PR?

ecreeth · 2019-06-17T14:51:16Z

@ecreeth can you remove these docs via a PR?

Of course yes!

SaraChicaD · 2019-06-18T20:06:13Z

On the Slider repo the Slider.js file matches the docs. On the RN web docs, which I understand are deprecated, onSlidingStart is missing.

Looks like Switch docs (in this repo) are also up-to-date with RN code.

AccessibilityInfo docs (in this repo) & RN code match.

jeremyscatigna · 2019-07-04T15:05:10Z

Would love to help! 🙌What could I do ?

mikeaustin · 2019-07-13T02:59:55Z

What I don't understand is how the core method of registering and running an app is not documented? AppRegistry.runApplication() has 0 documentation in https://facebook.github.io/react-native/docs/appregistry#runapplication. I Googled to find out what appParameters are supported, but actually didn't find much. Is there not a transition period where the docs are not empty?

orta · 2019-07-13T12:10:57Z

This sounds like a great opportunity for you to try and contribute to the docs @mikeaustin (/cc @jeremyscatigna also?) - looks like these are the params and here's the function

ecreeth · 2019-07-14T15:39:41Z

@cpojer Please update the list above with the PRs that were merged. 📦 💯 To know better what we are missing

BatDroid · 2019-08-18T22:14:09Z

I'm really interested in contributing to this repo. i've started working on SectionList but as a starter i have couple of questions that i would really appreciate if someone could help me with.

is it good if i re-order the props alphabetically?
renderItem is Optional in codebase. The reason is the functionality of rendering per item behaviour that if user use it then the renderItem will not be needed anymore. should i move it to optional props?
based on what is in the codebase about the legacyImplementation, The legacy implementation is no longer supported.. shall i add it to docs? (or there has been a reason that it isn't)
based on the codebase, the flashScrollIndicators seems to be only for ios. shall i add it to docs? (or there has been a reason that it hasn't been mentioned)
really sorry for these questions but if i get more familiar with these things, i'll do things faster.
ill make my pr after i get these answers. thank you

keshavkaul · 2019-08-22T11:33:06Z

@cpojer Can someone review this PR that changes the recommended way to setup a new react native library? The currently recommended way is to use react-native-create-library package. But this package is not being maintained. The PR recommends using create-react-native-module instead.

#1118

technoplato · 2019-08-28T05:45:33Z

If the introduction was about building a real app and was a connected step-by-step guide, that would be ideal.

I structured and laid out the redesign of Google’s Android Fundamentals course a couple years ago. Has this issue had any attention? If not, would something of a mimic of a weather fetching app be a good fit here? Would love to start contributing to the community and could also make accompanying tutorials if I had some editing help.

rachelnabors · 2020-02-05T18:24:56Z

We've moved the remaining tasks into a new ticket: #1579 Please go there to help us finish up the component docs and thanks for all your help thus far!

cpojer mentioned this issue May 15, 2019

📘 What would you like to learn about React Native? #917

Closed

cpojer changed the title ~~☂️Website Redesign and Documentation Rewrite~~ ☂️ Website Redesign and Documentation Rewrite May 15, 2019

dayhaysoos mentioned this issue May 15, 2019

Update view.md with new APIs for issue #929 #931

Merged

glauberfc mentioned this issue May 17, 2019

ScrollView method getScrollResponder is not listed in the document #768

Closed

This was referenced Jun 17, 2019

remove alertios.md #1033

Closed

remove imageeditor #1034

Closed

remove maskedviewios from sidebars #1035

Closed

remove ViewPagerAndroid #1036

Closed

remove asyncstorage #1037

Closed

remove statusbarios #1038

Closed

SaraChicaD mentioned this issue Jun 18, 2019

Updates Docs: Linking #1043

Merged

ecreeth mentioned this issue Jul 2, 2019

[Proposal] add tutorials section #1071

Closed

ecreeth mentioned this issue Jul 16, 2019

[Docs][New Guide Structure] Join props.md and state.md in the basics #1114

Merged

7 tasks

ecreeth mentioned this issue Jul 29, 2019

Update toastandroid.md #1152

Merged

BatDroid mentioned this issue Aug 19, 2019

Update sectionlist.md #1192

Merged

This was referenced Oct 22, 2019

Update modal.md #1425

Merged

Update picker.md #1433

Merged

Add snack player example to switch.md #1434

Merged

raajnadar mentioned this issue Dec 13, 2019

Guides for app icon and splashscreen both android & ios #1513

Closed

rachelnabors mentioned this issue Dec 31, 2019

New intro to React Native and React #1535

Merged

rachelnabors closed this as completed Feb 5, 2020

rachelnabors unpinned this issue Feb 5, 2020

Dexwell mentioned this issue Feb 22, 2020

Lack of examples and documentation matrix-org/matrix-js-sdk#608

Open

☂️ Website Redesign and Documentation Rewrite #929

☂️ Website Redesign and Documentation Rewrite #929

Comments

cpojer commented May 15, 2019 • edited

Goals

Redesign

New Guide Structure

Documentation Rewrite Tasks

API Docs

Guidelines

glauberfc commented May 15, 2019

cpojer commented May 15, 2019

saxenanickk commented May 15, 2019

glauberfc commented May 15, 2019 • edited

cpojer commented May 15, 2019

glauberfc commented May 15, 2019

dayhaysoos commented May 15, 2019

yangshun commented May 15, 2019

glauberfc commented May 15, 2019

dayhaysoos commented May 15, 2019

orta commented May 15, 2019

yangshun commented May 15, 2019

dayhaysoos commented May 15, 2019

yangshun commented May 15, 2019

zeabdelkhalek commented May 16, 2019

cpojer commented May 16, 2019

ksrini73 commented May 16, 2019 • edited

glauberfc commented May 16, 2019 • edited

cpojer commented May 16, 2019

glauberfc commented May 16, 2019 • edited

SSTPIERRE2 commented May 16, 2019

yangshun commented May 16, 2019

glauberfc commented May 16, 2019

yangshun commented May 16, 2019

dayhaysoos commented May 17, 2019

cpojer commented Jun 17, 2019

ecreeth commented Jun 17, 2019

SaraChicaD commented Jun 18, 2019 • edited

jeremyscatigna commented Jul 4, 2019

mikeaustin commented Jul 13, 2019

orta commented Jul 13, 2019

ecreeth commented Jul 14, 2019

BatDroid commented Aug 18, 2019

keshavkaul commented Aug 22, 2019

technoplato commented Aug 28, 2019

rachelnabors commented Feb 5, 2020

cpojer commented May 15, 2019 •

edited

glauberfc commented May 15, 2019 •

edited

ksrini73 commented May 16, 2019 •

edited

glauberfc commented May 16, 2019 •

edited

glauberfc commented May 16, 2019 •

edited

SaraChicaD commented Jun 18, 2019 •

edited