Clean and clarify the docs (#2713)

Co-authored-by: Tommy Nguyen <4123478+tido64@users.noreply.github.com>

README.md

@@ -1,41 +1,69 @@
-# React Native Developer Tools
+# `rnx-kit` - React Native tooling by and for developers
 
 [![Open in Visual Studio Code](https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&color=007acc&labelColor=444444&logoColor=007acc)](https://vscode.dev/github/microsoft/rnx-kit)
 [![Build](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml/badge.svg)](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml)
 
-### Modern, scalable tools. Exceptional developer experience.
+`rnx-kit` is a collection of battle-tested tools created by Microsoft engineers
+to optimize the React Native developer experience. It helps filling gaps in the
+React Native ecosystem and streamlines the developer workflow.
 
-You can find guides, documentation, resources, and our blog on the
-[project website](https://microsoft.github.io/rnx-kit).
+These tools are actively used every day to ship React Native apps at scale
+across Microsoft; now they're open source and available for any React Native
+project.
 
-### Made by Developers, for Developers.
+## What's included
 
-_Purpose-built for React Native engineers. Focused on developer experience.
-Designed to fit into any project, no matter how large or complex._
+`rnx-kit` includes tools for:
 
-_Great tools make all the difference._
+- Dependency management - Ensure consistent dependency versions across large
+  projects with `align-deps`.
+- Native builds (experimental) - Build Android and iOS apps in the cloud with
+  `build`. Avoid installing heavy native toolchains.
+- Better bundling - `metro-serializer` allows the enhancement of Metro to add
+  features such as TypeScript validation with Metro, tree shaking, duplicate and
+  cyclic dependencies detection.
+- Microsoft-tailored defaults - you can find Babel preset for Metro opinionated
+  for Microsoft usage.
 
-### Community First
+And many more!
 
-_Created as a GitHub-first repository for the React Native community. Integrated
-with tools you already use: Metro, TypeScript, Jest, and more._
+## Get started
 
-_Join in! Your contributions are always welcome._
+Please follow
+[Introduction guide](https://microsoft.github.io/rnx-kit/docs/introduction) on
+the documentation website to learn about how you can quickly add the "all in
+one" CLI to your project and get most of the tools set out of the box.
 
-### Tested at scale. Supported by Microsoft.
+Or follow the
+[Getting started guide](https://microsoft.github.io/rnx-kit/docs/guides/getting-started)
+for an easy introduction to our dependency management tool.
 
-_From unit tests to deployments in large monorepos, each tool is thoroughly
-validated. Microsoft has engineers dedicated to this project, using it to ship
-React Native apps to millions of customers._
+If you want to use only a specific tool, you can refer to its `README`` for
+details; they are all easily readable in the
+[Tools section](https://microsoft.github.io/rnx-kit/docs/tools/overview) of the
+documentation.
 
-### Contributing
+## Contributing
 
-Thank you for your interest in this project! We welcome all contributions and
-suggestions!
+`rnx-kit` is built for the community, by the community - and maintained by
+Microsoft engineers. Your contributions are welcome!
 
 Take a look at
 [CONTRIBUTING](https://github.com/microsoft/rnx-kit/tree/main/CONTRIBUTING.md)
 for details.
 
 If you are interested in proposing "substantial" changes, please refer to our
 [RFC process](https://github.com/microsoft/rnx-kit/tree/rfcs).
+
+## License
+
+[MIT License](LICENSE)
+
+## Code of Conduct
+
+This project has adopted the
+[Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the
+[Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any
+additional questions or comments.

docsite/docs/architecture/overview.md

@@ -5,7 +5,7 @@ want to understand **why**. What's going on inside of a particular tool? What
 decisions led to that design?
 
 Don't see the topic you're looking for? Do you have specific questions that
-aren't answered here? Take a look at the [Resources](../resources) area. You'll
+aren't answered here? Take a look at the [Community](../community) area. You'll
 find talks, podcasts, recorded streaming sessions, and other materials that may
 help you out. You'll also find links to the developer community where you can
 ask questions and get help.

docsite/docs/resources.mdx → docsite/docs/community.mdx

@@ -1,52 +1,45 @@
 import Image from "@site/src/components/Image";
 
-# Resources
-
-Need help? Have an idea or code you want to share? Looking to meet other
-developers using `rnx-kit`?
-
-You're in the right place!
+# Community
 
 The resources below are ways to reach us and the larger community. Plus, you'll
 find videos, talks, streaming sessions and podcasts, all about the tools in this
 project.
 
-## Social
+### Interact with us!
 
 <p>
-  <Image src="/img/tw-logo.svg" alt="Twitter Logo" width="24px">
-    <a href="https://twitter.com/afoxman4">Adam Foxman (@afoxman4)</a>
-  </Image>
-</p>
-
-<p>
-  <Image src="/img/discord-logo.svg" alt="Discord Logo" width="24px">
-    <a href="http://discordapp.com/users/478687383198498855">
-      Adam Foxman (afoxman#4801)
-    </a>
+  <Image src="/img/github-logo.svg" alt="GitHub Logo" width="24px" invertable>
+    The primary way to interact with us is via the rnx-kit{" "}
+    <a href="https://github.com/microsoft/rnx-kit/issues">Issues</a>
+    {", "}
+    <a href="https://github.com/microsoft/rnx-kit/discussions">Discussions</a>
+    {", and "}
+    <a href="https://github.com/microsoft/rnx-kit/issues">Project Board</a>{" "}
+    sections.
   </Image>
 </p>
 
 <p>
   <Image src="/img/tw-logo.svg" alt="Twitter Logo" width="24px">
-    <a href="https://twitter.com/ReactNativeMSFT">
-      React Native at Microsoft (@ReactNativeMSFT)
-    </a>
+    If you want to keep up with everything React Native at Microsoft, you can
+    follow our Twitter account{" "}
+    <a href="https://twitter.com/ReactNativeMSFT">@ReactNativeMSFT</a>
   </Image>
 </p>
 
-## Community
-
 <p>
-  <Image src="/img/github-logo.svg" alt="GitHub Logo" width="24px" invertable>
-    rnx-kit <a href="https://github.com/microsoft/rnx-kit/issues">Issues</a>
-    {", "}
-    <a href="https://github.com/microsoft/rnx-kit/discussions">Discussions</a>
-    {", and "}
-    <a href="https://github.com/microsoft/rnx-kit/issues">Project Board</a>
+  <Image src="/img/microsoft-logo.svg" alt="Microsoft Logo" width="24px">
+    You can also subscribe to the official{" "}
+    <a href="https://devblogs.microsoft.com/react-native/">
+      React Native at Microsoft devblog
+    </a>{" "}
+    to be in the loop with all the latest news.
   </Image>
 </p>
 
+### Keep up with React Native
+
 <p>
   <Image src="/img/react-logo.svg" alt="React Native Logo" width="24px">
     <a href="https://reactnative.dev/help">React Native Community</a>
@@ -59,7 +52,29 @@ project.
   </Image>
 </p>
 
-## Videos
+## Talks
+
+### Videos
+
+<iframe
+  src="https://www.youtube.com/embed/PYMMxfttOug"
+  title="Our Journey of Making React Native a Preferred Choice - Lorenzo Sciandra & Tommy Nguyen | RNEU 2023"
+  width="560"
+  height="315"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
+<iframe
+  src="https://www.youtube.com/embed/zgAjZVcvsv8"
+  title="Changing React Native... from within! - Adam Foxman | React Native EU 2022"
+  width="560"
+  height="315"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
 
 <iframe
   src="https://www.youtube.com/embed/-6oCo7lTRTw"
@@ -91,7 +106,7 @@ project.
   allowfullscreen
 ></iframe>
 
-## Podcasts
+### Podcasts
 
 <iframe
   src="https://player.simplecast.com/d07ef244-d829-491a-9bf2-aa681db7a8dd?dark=true"

docsite/docs/tools/overview.md

@@ -11,6 +11,6 @@ managing dependencies. Individual tools help you solve specific problem, like
 [making Metro work with symlinks](./metro-resolver-symlinks).
 
 If you get stuck or notice that something is missing, take a look at the
-[Resources](../resources) area. You'll find talks, podcasts, recorded streaming
+[Community](../community) area. You'll find talks, podcasts, recorded streaming
 sessions, and other materials that may help you out. You'll also find links to
 the developer community where you can ask questions and get help.

docsite/docusaurus.config.js

@@ -2,12 +2,13 @@
 
 // Ensure content is generated
 require("./generate")();
+const { themes } = require("prism-react-renderer");
 
-const darkCodeTheme = require("prism-react-renderer/themes/vsDark");
+const darkCodeTheme = themes.vsDark;
 
 /** @type {import("prism-react-renderer").PrismTheme} */
 // @ts-expect-error Type definition doesn't match up with actual export
-const lightCodeTheme = require("prism-react-renderer/themes/vsLight");
+const lightCodeTheme = themes.vsLight;
 lightCodeTheme.plain.color = "rgb(28, 30, 33)"; // from CSS --font-color-base-rgb
 lightCodeTheme.plain.backgroundColor = "#ffffff";
 
@@ -24,7 +25,7 @@ const title2 = "Developer Tools";
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: title1 + " " + title2,
-  tagline: "Modern, scalable tools. Exceptional developer experience.",
+  tagline: "Tools to boost your productivity. By and for the community.",
   url: "https://" + organizationName + ".github.io",
   baseUrl: "/" + projectName + "/",
   onBrokenLinks: "throw",
@@ -125,9 +126,9 @@ const config = {
           },
           {
             type: "doc",
-            docId: "resources",
+            docId: "community",
             position: "right",
-            label: "Resources",
+            label: "Community",
           },
           {
             type: "doc",

docsite/package.json

@@ -15,13 +15,13 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.2.0",
-    "@docusaurus/preset-classic": "^2.2.0",
-    "@tsconfig/docusaurus": "^1.0.6",
+    "@docusaurus/core": "^2.4.0",
+    "@docusaurus/preset-classic": "^2.4.0",
+    "@tsconfig/docusaurus": "^2.0.1",
     "clsx": "^1.2.1",
-    "prism-react-renderer": "^1.3.5",
-    "react": "17.0.2",
-    "react-dom": "17.0.2",
+    "prism-react-renderer": "^2.1.0",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
     "typescript": "^5.0.0"
   },
   "engines": {

docsite/src/components/HomepageFeatures.tsx

@@ -1,6 +1,6 @@
 import useBaseUrl from "@docusaurus/useBaseUrl";
-import React from "react";
 import clsx from "clsx";
+import React from "react";
 import styles from "./HomepageFeatures.module.css";
 
 type FeatureItem = {
@@ -12,16 +12,18 @@ type FeatureItem = {
 
 const FeatureList: FeatureItem[] = [
   {
-    title: "Made by developers, for developers.",
+    title: "For all developers",
     image: "/img/code-pull-request.svg",
     alt: "Pull-request icon",
     description: [
       <p key="dev1">
-        <strong>Purpose-built</strong> for React Native engineers. Focused on
-        developer experience. Designed to fit into <em>any</em> project, no
-        matter how large or complex.
+        <strong>Developer-centric tools</strong> built for React Native
+        engineers. Designed for real world needs - integrate into <em>any </em>
+        project, large or small.
+      </p>,
+      <p key="dev2">
+        Purpose-built to improve DX and streamline your workflow.
       </p>,
-      <p key="dev2">Great tools make all the difference.</p>,
     ],
   },
   {
@@ -35,7 +37,8 @@ const FeatureList: FeatureItem[] = [
         TypeScript, Jest, and more.
       </p>,
       <p key="com2">
-        Join in! Your contributions are <em>always</em> welcome.
+        Contributions from the community are key to shaping rnx-kit. Get
+        involved!
       </p>,
     ],
   },
@@ -45,10 +48,12 @@ const FeatureList: FeatureItem[] = [
     alt: "Flask icon",
     description: [
       <p key="test1">
-        From unit tests to deployments in large monorepos, each tool is{" "}
-        <strong>thoroughly validated</strong>. Microsoft has engineers dedicated
-        to this project, using it to ship React Native apps to millions of
-        customers.
+        Battle-tested at scale by Microsoft engineers. From unit tests to large
+        monorepos, these tools are <strong>thoroughly validated</strong>.
+      </p>,
+      <p key="com2">
+        Dedicated maintainers are ensuring rnx-kit evolves to meet the real
+        needs of Microsoft.
       </p>,
     ],
   },