Improve milo engineering docs

[hparra]

Problem

Milo has minimal (if not insufficient) engineering documentation within the repository. This reduces developer velocity by increasing pre-work of understanding how milo works.

We eschew traditional inline documentation to keep file size down, so it's understandable why this is. Unfortunately, documentation that would normally be generated is not placed anywhere. Sometimes a feature has markdown-based docs, but this is rare.

Solutions

I propose we agree on a recommendation for documentation within the repo.

Option 1

Use a docs/ folder, and create folders that mirror libs/, e.g. blocks, features, utils, etc. Pros: aggregated, flexible, optionally publishable. Cons: further from code, but still part of developer process (PR).

Option 2

Use READMEs within libs/. Pros: closest to code, render in github when browsing code folders. Cons: only one per folder, dispersed.

Option 3

Use existing wiki. Pros: exists, wysiwig. Cons: furthest from developer process as it's not part of code, not meeting needs prompted here.

Related

This is related to part of this https://github.com/orgs/adobecom/discussions/2836 but the scope is limited to engineering documentation only.

[hparra]

I vote for docs. Flexible and we can publish via Pages if we want. We could also use READMEs instead or together. In both cases the doc can be part of PR.

I'm not a fan of wiki at all. I completely forget it's there and we cannot include doc as part or PR. This encourages doc rot.