Adds some more docs to the website

orta · orta · commit 0b568e76b462 · 2020-09-29T11:52:58.000-04:00
diff --git a/README.md b/README.md
@@ -30,6 +30,8 @@ Some useful knowledge:
 
 You can manually via GH Actions for [production here](https://github.com/microsoft/TypeScript-Website/actions?query=workflow%3A%22Monday+Website+Push+To+Production%22) and [staging here](https://github.com/microsoft/TypeScript-Website/actions?query=workflow%3A%22Build+Website+To+Staging%22).
 
+Having issues getting set up? [Consult the troubleshooting](./docs/Setup Troubleshooting.md).
+
 ## Deployment
 
 Deployment is automatic:
@@ -39,9 +41,14 @@ Deployment is automatic:
 
 You can find the build logs in [GitHub Actions](https://github.com/microsoft/TypeScript-Website/actions)
 
-## Overview
+## Docs
+
+If you want to know _in-depth_ how this website works, there is an [hour long video covering the codebase, deployment and tooling on YouTube.](https://www.youtube.com/watch?v=HOvivt6B7hE). Otherwise there are some short guides:
 
-If you want to know _in-depth_ how this website works, there is an [hour long video covering the codebase, deployment and tooling on YouTube.](https://www.youtube.com/watch?v=HOvivt6B7hE).
+- [Converting Twoslash Code Samples](./docs/Converting Twoslash Code Samples.md)
+- [How i8n Works For Site Copy](./docs/How i8n Works For Site Copy.md)
+- [Updating the TypeScript Version](./docs/New TypeScript Version.md)
+- [Something Went Wrong](./docs/Something Went Wrong.md)
 
 # Website Packages
 
diff --git a/docs/New TypeScript Version.md b/docs/New TypeScript Version.md
@@ -37,6 +37,21 @@ Then run `yarn install`.
 
 That will update all of the site to use 3.9.0 for building. Run `yarn build` to see if any of the website's code broke.
 
+##### New Handbook Docs
+
+You might have a new reference doc to add, they live in [`packages/documentation/copy`](https://github.com/microsoft/TypeScript-website/blob/v2/packages/documentation/copy). You can ignore languages other than `en`. The folder structure is only for your reference and has no bearing on the site navigation. Each markdown document needs a header like:
+
+```md
+---
+title: Basic Types
+layout: docs
+permalink: /docs/handbook/basic-types.html
+oneline: "Step one in learning TypeScript: The basic types."
+---
+```
+
+Or the site will fail the build. Once that file is ready, add it to the sidebar via the file [`packages/documentation/scripts/generateDocsNavigationPerLanguage.js`](https://github.com/microsoft/TypeScript-website/blob/v2/packages/documentation/scripts/generateDocsNavigationPerLanguage.js).
+
 ##### TSConfig Reference
 
 Updating the version of TypeScript will force you to update the TSConfig Reference. It will fail incrementally with each missing compiler flag.
diff --git a/docs/Setup Troubleshooting.md b/docs/Setup Troubleshooting.md
@@ -0,0 +1,17 @@
+## Getting this Repo Set Up Troubleshooting
+
+#### Module `x` is not built
+
+Sometimes, and it's not been tracked down exactly, some dependencies of the site aren't built even though it says they are. In those cases, re-run `yarn bootstrap` and `yarn build` to re-build all the internal site deps.
+
+#### No syntax highlighting
+
+By default the website runs without twoslash code samples being evaluated, this affects the syntax highlighting. To turn it on, use `yarn start-twoslash` instead of `yarn start`.
+
+#### Windows + Watchman
+
+The Windows support for watchman is a bit meh. It's not likely to get better, given how well WSL works now. So, you _could_ use WSL to work around that.
+
+Though, for _a lot_ of changes to the site: Watchman is optional. All the watchman script does is run `yarn workspace [xxyy] build` when you save in a package which is not `typescriptlang-org` (the gatsby website).
+
+To run the site without watchman, use `yarn workspace typescriptlang-org start`.
diff --git a/docs/Something Went Wrong.md b/docs/Something Went Wrong.md
@@ -18,15 +18,13 @@ We're currently running on App Service, the places where you can find info:
 
 ### Deployment
 
-The build to deploy train looks like this:
+The build to deploy train normally looks like this:
 
-- `v2` branch gets pushed
-- pushes trigger a deploy to `SITE-STAGING` via GH Actions
-- Azure picks up pushes to SITE-STAGING to deploy to the site
+- `v2` branch gets pushed:
+- A deploy is made to azure blob storage via [`.github/workflows/v2-merged-staging.yml`](https://github.com/microsoft/TypeScript-website/blob/v2/.github/workflows/v2-merged-staging.yml)
+- Every Monday, a deploy is made from v2 to the production app via [`.github/workflows/deploy-prod.yml`](https://github.com/microsoft/TypeScript-website/blob/v2/.github/workflows/deploy-prod.yml)
 
-We deploy by pushing to the branches [`SITE-STAGING`](https://github.com/microsoft/TypeScript-Website/tree/SITE-STAGING/) and [`SITE-PRODUCTION`](https://github.com/microsoft/TypeScript-Website/tree/SITE-PRODUCTION/) - they should show you exactly what files exist in the deploy
-
-You can push directly to those branches from your local computer if you have a very specific fix
+You can deploy `v2` to production anytime via the ["Run workflow" button here](https://github.com/microsoft/TypeScript-Website/actions?query=workflow%3A%22Monday+Website+Push+To+Production%22), so if you have an emergency commit - it goes to `v2` then you can run the action.
 
 App Service apps are configured by [`Web.config`](https://github.com/microsoft/TypeScript-website/blob/92a9585d033e7cf802fae14v22baa73250fd610266/packages/typescriptlang-org/static/Web.config). [Here's a reference on the format](https://hangouts.google.com/call/H553wrJ9d97l2LMpNh9hAEEE). I've seen files (`*.json` & `*.manifest`) be 404s on the site because they were not in the config.
 
