Per-Project, Field-Level Documentation

[benpate]

Cross-posting from a thread in the Fediverse Devs matrix chat..

Another major pain point for me is that ActivityStreams as too flexible. I never know what I'll find in any particular field. It could be:

• a simple atomic string
• a language-based lookup in a separate property object
• a URL that points to where the real data is stored in an object with more details that I might need but maybe not
• or an array containing any one or all of these kinds of data that will absolutely break in a strongly-typed data model.

My point is not to complain, but to put forward another goal for this group, which would be making some recommendations for what data should really go here, at least as a starting point, to give devs some confidence in what data they're looking for.

I don't know how deep we could/should go, but there are tons of examples or really good developer docs out there. I've always been impressed with Stripe's developer site. So in my mind, the ideal documentation would look something like Stripe's API documents: