Repository: TypeScript
Issue: The project references documentation should include working examples
Labels: Docs,Rescheduled

# Suggestion

<!--
  Please fill in each section completely. Thank you!
-->

## 🔍 Search Terms
<!--
  💡 Did you know? TypeScript has over 2,000 open suggestions!
  🔎 Please search thoroughly before logging new feature requests as most common ideas already have a proposal in progress.
  The "Common Feature Requests" section of the FAQ lists many popular requests: https://github.com/Microsoft/TypeScript/wiki/FAQ#common-feature-requests

  Replace the text below:
-->

tsconfig, tsconfig.json, project references, documentation, references

## ✅ Viability Checklist

<!--
   Suggestions that don't meet all these criteria are very, very unlikely to be accepted.
   We always recommend reviewing the TypeScript design goals before investing time writing
   a proposal for ideas outside the scope of the project.
-->
My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).


## ⭐ Suggestion

<!-- A summary of what you'd like to see added or changed -->

This part of the documentation starts with this example: https://www.typescriptlang.org/docs/handbook/project-references.html#an-example-project

```
/
├── src/
│   ├── converter.ts
│   └── units.ts
├── test/
│   ├── converter-tests.ts
│   └── units-tests.ts
└── tsconfig.json
```

The docs say:

> Previously, this structure was rather awkward to work with if you used a single tsconfig file ... Project references can solve all of these problems and more ... The path property of each [project] reference can point to a directory containing a tsconfig.json file, or to the config file itself (which may have any name)

So it says. But the documentation never shows how to use project references to get *this* structure working, and that's what my project looks like.

I'd like the documentation to show how to get this example working, which would require showing what all three tsconfig's look like. 

EDIT: [I asked how to do this on stackoverflow but have not received an answer.](https://stackoverflow.com/questions/70869057/how-do-i-use-tsconfig-references-for-a-project-that-has-separate-src-and-test-di)

## 📃 Motivating Example

The documentation now explains how to use project references in greater detail.

<!--
  If you were announcing this feature in a blog post, what's a short explanation that shows
  a developer why this feature improves the language?
-->

## 💻 Use Cases

<!--
  What do you want to use this for?
  What shortcomings exist with current approaches?
  What workarounds are you using in the meantime?
-->

I can't figure out how to get the documentation's own example to run without error. With so many available tsconfig properties and without seeing what the tsconfig files should look like for these examples, the possibilities are nearly endless. 

My workaround is to avoid projects with the example structure.