Add post on the #![doc = include_str!("")] pattern

[DJMcNab]

This is a trick I invented? discovered? stumbled upon? whilst creating Android Trace, and thought it was worth documenting; I believe that we should use this throughout our crates. It's currently used in Android Trace and Xilem Core

Depends on linebender/android_trace#11 because of the example; I want to wait until I have done a patch release of Android Trace before publishing

Unblocked

[PoignardAzur]

It's a neat trick, but I'm not super comfortable with the amount of workarounds it introduces.

I'd rather copy-paste the same doc twice, and maybe use some sort of automated tool to check that the README and the root doc match.

[DJMcNab]

As in my conclusion, my point with this pattern is not that it's necessarily the best possible status quo; maintaining docs tailored for each is best. But, I think:

• If you're copying and pasting docs, they are inevitably not going to keep in sync
• unless you have that being validated, which requires tooling that we don't have

And so for the stage in their lifecycle that our projects are at (and which I would argue many projects are at), I believe these workarounds are worthwhile. That is, the status quo is not ideal, and I think that this is an easy way to get to a better set of tradeoffs.

[Philipp-M]

Sorry that this hasn't got attention, IIRC there wasn't really reluctance in previous office hours, so I'll just approve it.

The pattern is obviously not perfect, but I like having to maintain only a single source of truth (with a few gotchas). And I've actually used it now in xilem_web too.

[Philipp-M]

Still LGTM with the new changes.

[DJMcNab]

I'm merging. This isn't a commitment for us to use this pattern, and I'd happily move to something better. But I think it's a pattern which is worth publicizing