From 9dc1c95f03d20a293524b1b5320d1c2cb260b1d6 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Thu, 12 Nov 2020 18:28:24 +0000
Subject: [PATCH] FAQ: Link to building.md and enhance it

Now that the source is on GH we can say so!  While we're here
let's enhance the building docs.
---
 docs/building.md | 30 ++++++++++++++++++++++++++++--
 docs/faq.md      |  7 +------
 2 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/docs/building.md b/docs/building.md
index 452878c788..7cd99e217c 100644
--- a/docs/building.md
+++ b/docs/building.md
@@ -1,6 +1,32 @@
-# Building RHCOS
+# Background
 
-You need to create a `rhcos.repo` file that looks like this:
+RHCOS is a derivative of both RHEL and Fedora CoreOS.  The tool
+to build both RHCOS and FCOS is [coreos-assembler](https://github.com/coreos/coreos-assembler/).
+See the upstream documentation there first, and pull down
+the container.
+
+coreos-assembler (or "cosa") accepts a configuration git repository
+as input.  This repository is that configuration for RHCOS,
+just like [fedora-coreos-config](https://github.com/coreos/fedora-coreos-config)
+is for FCOS.
+
+For example, you would use
+```
+$ cosa init https://github.com/openshift/os
+```
+
+to start.  However, currently you need to configure
+the rpm-md repositories manually:
+
+# Repositories
+
+The RHEL repositories are only available to Red Hat customers,
+and it's likely that you want to use a mirror.  And further,
+a common scenario is to inject specific versioned rpm-md repositories
+to test different snapshots or "composes".  For these reasons,
+you need to provide the repos of input RPMs.
+
+To do so, create a `rhcos.repo` file that looks like this:
 
 ```
 # RHEL repos
diff --git a/docs/faq.md b/docs/faq.md
index 1bf7d5c911..2c3fba5a05 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -141,12 +141,7 @@ that are fixed in newer versions of the package.
 
 ## Q: How do I build my own version of RHCOS for testing?
 
-You need the RHCOS manifest configuration (currently hosted on an RHT internal [GitLab repo](https://url.corp.redhat.com/rhcos-repo)) and
-[coreos-assembler](https://github.com/coreos/coreos-assembler).
-
-If you want to replace particular binaries or RPMs in RHCOS, the `coreos-assembler` has
-[override mechanisms](https://github.com/coreos/coreos-assembler/blob/master/README-devel.md#using-overrides)
-to do this.
+See [building.md](building.md).
 
 Also reference the docs from the `machine-config-operator` about
 [hacking on the `machine-os-content`](https://github.com/openshift/machine-config-operator/blob/master/docs/HACKING.md#hacking-on-machine-os-content)