Making changes to doc as per suggestions

docs/files.md

@@ -108,7 +108,7 @@ sdists-repo
 └── downloads
 ```
 
-The `builds` and `downloads` sub-directories contain the source distributions that are built and downloaded respectively in `tar.gz` format. For example, the `sdists-repo` for `stevedore` package looks as follows:
+The `builds` and `downloads` sub-directories contain the source distributions that are built and downloaded respectively in `tar.gz` format. The `downloads` directory includes the original sdist from upstream and the `builds` directory contains the sdist created by fromager after any patches are applied. For example, the `sdists-repo` for `stevedore` package looks as follows:
 
 ```
 sdists-repo
@@ -137,10 +137,10 @@ wheels-repo
 └── simple
 ```
 
-* The `build` sub-directoy contains the configuration information related to the wheel build
-* The `downloads` sub-directory contains the wheels in `.whl` format that were downloaded from an index
+* The `build` sub-directoy holds temporary builds. We use it as the output directory when building the wheel because we can't predict the filename, and so using an empty directory with a name we know gives us a way to find the file and move it into the `downloads` directory after it's built
+* The `downloads` sub-directory contains the wheels in `.whl` format that fromager builds combined with the pre-built wheels so we can create a local package index in `simple`
 * The `prebuilt` sub-directory contains wheels that are being used as prebuilt
-* The `simple` sub-directory consists of sub-directories that include wheels built by fromager in `whl` format along with an `index.html` file which contains the link to download the wheel. The `index.html` file present at the root level of this directory includes links to download wheels for the package and its dependencies
+* The `simple` sub-directory is managed by [pypi-mirror](https://pypi.org/project/pypi-mirror/) to create a local wheel index.
 
 For example, the `wheels-repo` for `stevedore` package looks as follows:
 
@@ -177,6 +177,7 @@ work-dir
 ├── graph.json
 ├── logs
 ├── sample-package-foo
+   ├── simple-package-foo
    ├── build-backend-requirements.txt
    ├── build.log
    ├── build-meta.json
@@ -186,16 +187,16 @@ work-dir
 
 ```
 
-* The `build-order.json` file is an output file that contains the bottom-up order in which the dependencies need to be built for a specific wheel
-* The `constraints.txt` is the input file used to control the resolution of python packages that are needed to build a wheel
-* The `graph.json` is an output file that contains all the paths fromager can take to resolve a dependency during building the wheel
-* The `logs` sub-directory contains detailed logs for fromager's `build-sequence` command including various settings and overrides for each individual package and its dependencies whose wheel was built by fromager
-* The `work-dir` also includes sub-directories for the package and its dependencies. These sub-directories include various types of requirements files including `build-backend-requirements.txt`, `build-sdists-requirements.txt`, `build-system-requirements.txt` and the general `requirements.txt`. Files like `build.log` which store the logs generated by PyPI and `build-meta.json` that stores the metadata for the build are also located in `work-dir`. These sub-directories also include all the other relevant information for a particular package
+* The `build-order.json` file is an output file that contains the bottom-up order in which the dependencies need to be built for a specific wheel. You can find more details [here](https://fromager.readthedocs.io/en/latest/files.html#build-order-json)
+* The `constraints.txt` is the output file, produced by fromager, showing all of the versions of the packages that are install-time dependencies of the top-level items
+* The `graph.json` is an output file that contains all the paths fromager can take to resolve a dependency during building the wheel. You can find more details [here](https://fromager.readthedocs.io/en/latest/files.html#graph-json)
+* The `logs` sub-directory contains detailed logs for fromager's `build-sequence` command including various settings and overrides for each individual package and its dependencies whose wheel was built by fromager. Each log file also contains information about build-backend dependencies if present for a given package.
+* The `work-dir` also includes sub-directories for the package and its dependencies. These sub-directories include various types of requirements files including `build-backend-requirements.txt`, `build-sdists-requirements.txt`, `build-system-requirements.txt` and the general `requirements.txt`. Files like `build.log` which store the logs generated by pip and `build-meta.json` that stores the metadata for the build are also located in `work-dir`. These sub-directories also include all the other relevant information for a particular package. Each sub-directory of the package will also contain the unpacked source code of each wheel that is used for the build if `--no-cleanup` option of fromager is used. For example, in the above directory structure, for `simple-package-foo` requirement, we will have a subdirectory titled `simple-package-foo` that holds the unpacked source code 
 
 For example, the `work-dir` for `stevedore` package after `bootstrap` command looks as follows:
 
 ```
-.
+work-dir
 ├── build-order.json
 ├── constraints.txt
 ├── graph.json