跳至主要内容

迈向更好的文档

·阅读时长 4 分钟
Kevin Lacker
Kevin Lacker
Facebook 工程经理

提供良好的开发者体验的一部分是提供出色的文档。创建良好的文档需要付出很多努力 - 理想的文档应简洁、实用、准确、完整且令人愉悦。最近，我们一直在根据您的反馈努力改进文档，并且我们想分享我们所做的一些改进。

内联示例​

当您学习一个新的库、一门新的编程语言或一个新的框架时，您第一次编写一小段代码、尝试一下、看看它是否有效……并且它确实有效，这将是一个美好的时刻。您创造了一些真实的东西。我们希望将这种切身的体验直接融入我们的文档中。就像这样

import React, { Component } from 'react';
import { AppRegistry, Text, View } from 'react-native';

class ScratchPad extends Component {
  render() {
    return (
      <View style={{flex: 1}}>
        <Text style={{fontSize: 30, flex: 1, textAlign: 'center'}}>
          Isn't this cool?
        </Text>
        <Text style={{fontSize: 100, flex: 1, textAlign: 'center'}}>
          👍
        </Text>
      </View>
    );
  }
}

AppRegistry.registerComponent('ScratchPad', () => ScratchPad);

我们认为，这些内联示例（使用 react-native-web-player 模块，并在 Devin Abbott 的帮助下）是学习 React Native 基础知识的好方法，并且我们已经更新了我们的 针对新 React Native 开发人员的教程 以尽可能多地使用这些示例。查看一下 - 如果您曾经好奇修改一小段示例代码会发生什么，这是一种非常好的探索方法。此外，如果您正在构建开发者工具，并且想要在您自己的网站上展示一个实时的 React Native 示例，react-native-web-player 可以使这变得简单直接。

核心模拟引擎由 Nicolas Gallagher 的 react-native-web 项目提供，该项目提供了一种在 Web 上显示 React Native 组件（如 Text 和 View）的方法。如果您有兴趣构建共享大量代码库的移动和 Web 体验，请查看 react-native-web。

改进的指南​

在 React Native 的某些部分，有多种方法可以执行操作，我们已经收到反馈，我们可以提供更好的指导。

我们有一个新的 导航指南，它比较了不同的方法并建议您应该使用什么 - Navigator、NavigatorIOS、NavigationExperimental。从中期来看，我们正在努力改进和整合这些接口。从短期来看，我们希望一个更好的指南能让您的生活更轻松。

我们还有一个新的 处理触摸指南，它解释了创建类似按钮的界面的一些基础知识，以及处理触摸事件的不同方法的简要概述。

我们改进的另一个领域是 Flexbox。这包括有关如何 使用 Flexbox 处理布局 以及如何控制 组件大小 的教程。它还包括一个不那么性感但希望有用的 控制 React Native 中布局的所有 props 的列表。

入门​

当您开始在您的机器上设置 React Native 开发环境时，您确实需要执行一些安装和配置操作。很难让安装成为一种真正有趣和令人兴奋的体验，但我们至少可以使其尽可能快且无痛。

我们构建了一个 新的入门工作流程，它允许您预先选择您的开发操作系统和移动操作系统，以提供一个包含所有设置说明的简洁位置。我们还经历了安装过程以确保一切正常，并确保每个决策点都有明确的建议。在对我们无辜的同事进行测试后，我们非常确定这是一个改进。

我们还改进了 将 React Native 集成到现有应用的指南。许多使用 React Native 的大型应用（例如 Facebook 应用本身）实际上是使用 React Native 构建应用的一部分，并使用常规开发工具构建应用的另一部分。我们希望本指南能让更多人更容易地以这种方式构建应用。

我们需要您的帮助​

您的反馈让我们知道我们应该优先考虑什么。我知道有些人会阅读这篇博文并认为“更好的文档？切。X 的文档仍然很糟糕！”。这很好 - 我们需要这种活力。提供反馈的最佳方式取决于反馈的类型。

如果您在文档中发现错误，例如不准确的描述或无法正常工作的代码，请 提交问题。将其标记为“文档”，以便更容易将其路由到合适的人员。

如果没有任何特定的错误，但文档中的某些内容从根本上令人困惑，那么它不适合 GitHub 问题。相反，请在 Canny 上发布有关需要帮助的文档部分的信息。这有助于我们在进行更一般的指南编写工作时确定优先级。

感谢您阅读至此，并感谢您使用 React Native！