跳到主要内容

迈向更好的文档

·5 分钟阅读
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 Gallagherreact-native-web 项目提供,该项目提供了一种在 Web 上显示 TextView 等 React Native 组件的方法。如果你有兴趣构建共享大部分代码库的移动和 Web 体验,请查看 react-native-web

更好的指南

在 React Native 的某些部分,有多种方法可以实现同一个目标,我们收到了反馈,认为我们可以提供更好的指导。

我们有一份新的导航指南,比较了不同的方法,并就您应该使用什么提供了建议——NavigatorNavigatorIOSNavigationExperimental。在中期,我们正在努力改进和整合这些接口。在短期内,我们希望一份更好的指南能让您的工作更轻松。

我们还有一份新的触控处理指南,解释了创建类似按钮界面的基础知识,并简要概述了处理触控事件的不同方法。

我们工作的另一个领域是 Flexbox。这包括关于如何使用 Flexbox 处理布局以及如何控制组件大小的教程。它还包括一份不起眼但希望能有用的React Native 中控制布局的所有属性列表

入门

当您开始在机器上设置 React Native 开发环境时,确实需要安装和配置一堆东西。很难让安装成为一个真正有趣和令人兴奋的体验,但我们至少可以使其尽可能快速和轻松。

我们构建了一个新的入门流程,让您可以预先选择您的开发操作系统和移动操作系统,以便在一个简洁的地方提供所有设置说明。我们还仔细检查了安装过程,确保一切正常工作,并确保每个决策点都有明确的建议。在我们的无辜同事身上测试后,我们非常确定这是一个改进。

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

我们需要您的帮助

您的反馈让我们知道应该优先处理什么。我知道有些人读完这篇博客文章后会想:“更好的文档?哼。X 的文档还是垃圾!”。这太好了——我们需要这种能量。提供反馈的最佳方式取决于反馈的类型。

如果您发现文档中的错误,例如描述不准确或代码实际无法工作,请提交一个 Issue。将其标记为“Documentation”,以便更容易将其转交给合适的人员。

如果没有具体的错误,但文档中的某些内容根本令人困惑,那么它不太适合作为 GitHub Issue。相反,请在 Canny 上发布关于文档中需要改进的领域的信息。这有助于我们在进行编写指南等更普遍的工作时确定优先顺序。

感谢您阅读到这里,也感谢您使用 React Native!