TechDocs annotation should have a sensible default

Feature Suggestion

Assuming a company is not using mono-repos, the docs are likely in the docs directory at the root of the repo that contains the component. Can we make this the default in order to make the techdocs-ref annotation optional?

Possible Implementation

No idea 😄

Context

Adoption of TechDocs is more likely if the user has to do less work to configure it. Every little bit of friction counts.

[andrewthauer]

Adding to this discussion, we are currently in the process of taking the “remove the friction” a step further. We’ve built code that will auto create an mkdocs.yml file dynamically in CI which means a repo really only needs a docs directory and an index/readme file. At that point we can auto build/publish the docs to storage. Then we have a custom processor that checks the existence of the docs directory for the entity and enriched the entity with the techdocs annotation. The difference being there is actually no physical mkdocs.yml file that is persisted anywhere.

[freben]

An out-of-the-box available processor that scans for an mkdocs file or properly detects an interesting docs dir sounds like it would be very useful!

@backstage/techdocs-core Could you chime in here? This sounds like a worthwhile contribution, whether by maintainers or by the community. I’ll actually slap a help wanted label on it in the mean time.