please document project references and outdir

Really really unclear documentation regarding the behavior of "project references" and outDir.

I can't believe how unclear this is -- please please tell me how I'm supposed to do this ...

> checkmate-node-monorepo@0.0.1 build /Users/ncohen/software/itsacheckmate.com/Web
> tsc --build --verbose

[11:01:04 AM] Projects in this build:
    * lib/pdf-api/tsconfig.json
    * tsconfig.json

[11:01:04 AM] Project 'lib/pdf-api/tsconfig.json' is out of date because output file 'lib/pdf-api/src/DoordashFailureSamples.js' does not exist

[11:01:04 AM] Building project '/Users/ncohen/software/itsacheckmate.com/Web/lib/pdf-api/tsconfig.json'...

[11:01:07 AM] Project 'tsconfig.json' is out of date because oldest output 'lib/pdf-api/src/DoordashPdfSemantics.js' is older than newest input 'lib/pdf-api'

[11:01:07 AM] Building project '/Users/ncohen/software/itsacheckmate.com/Web/tsconfig.json'...

[11:01:09 AM] Updating unchanged output timestamps of project '/Users/ncohen/software/itsacheckmate.com/Web/tsconfig.json'...

ncohen@breathe-book ~/s/i/Web> cat tsconfig.json
{
  "references": [{ "path": "./lib/pdf-api" }]
}

ncohen@breathe-book ~/s/i/Web> cat ./lib/pdf-api/tsconfig.json
{
  "extends": "../../tsconfig_base.json",
  "include": ["./src/**/*.ts"],
  "exclude": ["node_modules"]
}

ncohen@breathe-book ~/s/i/Web> cat ./tsconfig_base.json
{
  "compilerOptions": {
    "composite": true,
    "outDir": "compiled-js",
    "target": "es2016",
    "lib": ["es2016"],
    "module": "commonjs",
    "moduleResolution": "node",
    "sourceMap": true,
    "experimentalDecorators": false,
    "pretty": true,
    "strict": true,
    "strictFunctionTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "forceConsistentCasingInFileNames": true,
    "strictNullChecks": true,
    "declaration": true,
    "declarationMap": true
  }
}

Why are compiled files being written to ./lib/pdf-api/src/ directory? How can I have that NOT happen? Or if I have to have something written to my src directory (for some reason ...?) can I have only a single file written there which I can reliable gitignore ...?

ncohen@breathe-book ~/s/i/Web> tsc --version
Version 3.5.2

Start by reproducing the reported tsc --build --verbose behavior with tsconfig.json, lib/pdf-api/tsconfig.json, and tsconfig_base.json on TypeScript 3.5.2. Read the project references and outDir documentation alongside these configurations. Done means the documentation explains why outputs appear under lib/pdf-api/src and clearly describes supported ways to control or ignore generated files.