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:

[benpate]

Paraphrased from the Matrix chat: Thinking about this more, this should almost follow the caniuse.com format, with a table for each activity that lists specific fields and the cross-product of apps that support them. Here's a simple, made-up example of something that would work:

Field	WriteFreely	Mastodon	PixelFed	Streams	Lemmy	Emissary
{
name:	String	String	Mapped String	String	Mapped String	String
email:	String	-	-	String	String	String
photo:	URL	URL	Object	-	Object	URL
}

This looks like it might be a lot of work, and it might be overkill. But even if it only covered a few common activities, it would be supremely valuable for new implementors. And if this job was opened up to the maintainers of each app, it might even give them a way to compare and compete over who has the best support for various activities.

[gabek]

I do think having an accurate table of every object and how every platform uses them may be a lot of work. But maybe instead we can call out exceptions to the norm, or issues for specific scenarios that would catch people up. For example in the documentation for hashtags we cold call out how if you don't send hashtags as an array to Mastodon they'll throw out the activity.

Or for the documentation of the Create activity we can call out how Mastodon will throw out your activity if you send more than one object (for example a Note and an Event).

(These are just two examples I had at the top of my head).

What do you think of that?

[benpate]

Yeah, even putting this together, it started seeming like a lot of work. I'm still brainstorming up some kind of middle ground - perhaps we find a common format like, or inspired by Swagger, where everyone can document how THEY'RE doing it, which helps us compare implementations?

[gabek]

I originally thought like you do that every project should document how they're using things, and that's how the https://fedidevs.org/category/projects page started. I quickly realized it doesn't make as much sense to me as I thought simply because the amount of data required, and the amount of participation required from so many people. It's probably just not possible. People are busy and aren't going to spend time building specialized docs that adhere to what we're looking for. Especially the bigger projects, they simply won't care about what we're doing.

I also hope that in most cases people use things in a similar way, and it's easier to document what doesn't work between projects than to document every way it does work between projects. Reading through 40 examples of people's similar implementation of Note probably isn't terribly useful. But reading one example of how project X totally screws up how Note works and that's why it's not working for you when testing it might be easier to consume.

But this is just my current thoughts on things. As a developer I don't need to know everything about every project, I just need to know what impacts me right now. But I'm not strongly opinionated either way, I'm just trying to be realistic :)

[benpate]

Yeah, I follow you, and I think you're probably right and it's not a realistic thing to ask everyone to do. Hopefully you think I'm not crazy for wanting it though? Maybe we just pin our hopes on a well-documented reference implementation that everyone is able to reference?

[gabek]

No not crazy for wanting it at all! A complete, accurate and continuously updated table with details about each project to cross reference would certainly be great.

I still think there's opportunities for individual projects to publish their own details, and we can encourage that, but we can't rely on it. And most likely each project's documentation will look differently. But that would still be a fantastic resource when learning about a particular project and how they do things.

[benpate]

Yes, and thanks. I'm going to try to set a good example with my project, and perhaps test the waters on the best way to document this kind of thing. I'm certainly open to suggestions if anyone has better ideas. Maybe we can stumble onto a recommendation that others can follow.