Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

☂️ Website Redesign and Documentation Rewrite #929

Open
cpojer opened this issue May 15, 2019 · 44 comments

Comments

@cpojer
Copy link
Contributor

commented May 15, 2019

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

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!

  • Components
    • ActivityIndicator
    • Button
    • DatePickerIOS
    • DrawerLayoutAndroid
    • FlatList
    • Image
    • ImageBackground
    • InputAccessoryView
    • KeyboardAvoidingView
    • Modal
    • Picker
    • PickerIOS
    • ProgressBarAndroid
    • ProgressViewIOS
    • RefreshControl
    • SafeAreaView
    • ScrollView
    • SectionList
    • SegmentedControlIOS
    • Slider
    • StatusBar
    • Switch
    • Text
    • TextInput
    • ToolbarAndroid
    • TouchableHighlight
    • TouchableNativeFeedback
    • TouchableOpacity
    • TouchableWithoutFeedback
    • View
    • ViewPagerAndroid
    • VirtualizedList
  • APIs
    • AccessibilityInfo
    • ActionSheetIOS
    • Alert
    • AlertIOS
    • Animated
    • AppRegistry
    • AppState
    • AsyncStorage
    • BackHandler
    • CameraRoll
    • Clipboard
    • DatePickerAndroid
    • Dimensions
    • Easing
    • ImageEditor
    • ImagePickerIOS
    • Image Style Props
    • InteractionManager
    • Keyboard
    • Layout Props
    • LayoutAnimation
    • Linking
    • ListViewDataSource
    • PanResponder
    • PermissionsAndroid
    • PixelRatio
    • PushNotificationIOS
    • Settings
    • Shadow Props
    • Share
    • StatusBarIOS
    • StyleSheet
    • Systrace
    • Text Style Props
    • TimePickerAndroid
    • ToastAndroid
    • Transforms
    • Vibration
    • View Style Props

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.

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

@glauberfc

This comment has been minimized.

Copy link
Contributor

commented May 15, 2019

Can this website be made w/ Gatsby?

@cpojer

This comment has been minimized.

Copy link
Contributor Author

commented May 15, 2019

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

@saxenanickk

This comment has been minimized.

Copy link

commented May 15, 2019

Would love to contribute in this.

@glauberfc

This comment has been minimized.

Copy link
Contributor

commented May 15, 2019

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

  1. 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,
  1. Should the props be listed on alphabetical order?

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

Screen Shot 2019-05-15 at 12 13 59 PM

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

This comment has been minimized.

Copy link
Contributor Author

commented May 15, 2019

@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

This comment has been minimized.

Copy link
Contributor

commented May 15, 2019

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

This comment has been minimized.

Copy link
Contributor

commented May 15, 2019

I got dibs on View and Text!

@yangshun

This comment has been minimized.

Copy link
Member

commented May 15, 2019

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

@glauberfc

This comment has been minimized.

Copy link
Contributor

commented May 15, 2019

@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"

dayhaysoos added a commit to dayhaysoos/react-native-website that referenced this issue May 15, 2019

Update view.md with new APIs for issue facebook#929
☂️☂️☂️☂️☂️☂️ 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

This comment has been minimized.

Copy link
Contributor

commented May 15, 2019

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

@orta

This comment has been minimized.

Copy link
Contributor

commented May 15, 2019

Make the high level sections in the sidebar collapsible.

I think this is 'just' updating docusaurus BTW

@yangshun

This comment has been minimized.

Copy link
Member

commented May 15, 2019

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

This comment has been minimized.

Copy link
Contributor

commented May 15, 2019

@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

This comment has been minimized.

Copy link
Member

commented May 15, 2019

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

@AbdelkhalekESI

This comment has been minimized.

Copy link

commented May 16, 2019

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

@cpojer

This comment has been minimized.

Copy link
Contributor Author

commented May 16, 2019

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

@ksrini73

This comment has been minimized.

Copy link

commented May 16, 2019

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

@glauberfc

This comment has been minimized.

Copy link
Contributor

commented May 16, 2019

@cpojer:

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

  2. scrollsToTop was changed by onScrollToTop?

@cpojer

This comment has been minimized.

Copy link
Contributor Author

commented May 16, 2019

@glauberfc

  1. 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
  2. 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

This comment has been minimized.

Copy link
Contributor

commented May 16, 2019

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

This comment has been minimized.

Copy link

commented May 16, 2019

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

This comment has been minimized.

Copy link
Member

commented May 16, 2019

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

@glauberfc

This comment has been minimized.

Copy link
Contributor

commented May 16, 2019

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

This comment has been minimized.

Copy link
Member

commented May 16, 2019

@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

This comment has been minimized.

Copy link
Contributor

commented May 17, 2019

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

This comment has been minimized.

Copy link
Contributor Author

commented Jun 17, 2019

@ecreeth thank you so much for doing this! I just updated the list above :)

This was referenced Jun 17, 2019

@ecreeth

This comment has been minimized.

Copy link
Contributor

commented Jun 17, 2019

@cpojer The following components or API's have been removed, moved or merged:

  • AlertIOS see #23318
  • CameraRoll moved here. But not completely removed from React Native see here
  • ImageEditor moved here
  • ListViewDataSource I could not find anything about this
  • ViewPagerAndroid moved here
@cpojer

This comment has been minimized.

Copy link
Contributor Author

commented Jun 17, 2019

@ecreeth can you remove these docs via a PR?

@ecreeth

This comment has been minimized.

Copy link
Contributor

commented Jun 17, 2019

@ecreeth can you remove these docs via a PR?

Of course yes!

@SaraChicaD

This comment has been minimized.

Copy link
Contributor

commented Jun 18, 2019

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

This comment has been minimized.

Copy link

commented Jul 4, 2019

Would love to help! 🙌What could I do ?

@mikeaustin

This comment has been minimized.

Copy link

commented Jul 13, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Jul 13, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Jul 14, 2019

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

@BatDroid

This comment has been minimized.

Copy link

commented Aug 18, 2019

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.

  1. is it good if i re-order the props alphabetically?
  2. 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?
  3. 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)
  4. 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
You can’t perform that action at this time.