Document how source content works

[chrismatix]

Current state

We have a "as transparent as possible" approach to dealing with source messages and event payloads, which we acquired through years of operating a multi-source streaming messaging system. This is not reflected in the docs

Desired state Whenever there is a source content field in the APIs there should be a document page that we can point to that explains what kind of values users can expect on this field.

[lucapette]

I think I would add a section in this document: https://airy.co/docs/core/sources/introduction called "Content". We explain we have no opinion about the content of the messages and people should refer to the docs of the source provider to construct valid payloads (as we also do not validate them)

[chrismatix]

I think the idea for the content is good, but "concepts" seems an even better section because this topic encapsulates unique learnings we made. So we could have it at concepts/source-content and link that in the sources introduction.

[lucapette]

Agreed. Loved the suggestion!