Easing the onboarding of new developers to the Fediverse

[aschrijver]

(This is a continuation of Discussing onboarding for developers which veered into technical discussion)

TL;DR

Onboarding new devs to AP/Fediverse is a weak spot that is hampering the evolution (speed) of the ecosystem. Information is super-fragmented and many of the complexities are not readily obvious. Starting new projects is an adventure for the brave.

There are efforts to improve this, but time-constraints of experts and - in general - lack of appetite to do the work involved, means this process is very slow.

What can we do to change this?

Objective

• Set up a good-enough organization to start with
• Devise a process to make crowdsourcing of dev-docs easy

Background

I continuously witness would-be AP devs struggling. The newbie experience to AP is not good. On the fedi itself I see people asking questions, and they don’t know about the existence of SocialHub or the Feneas forums. Devs literally have to look everywhere to get their info together, delve into various codebases, reverse engineer for their own use case. Want to implement C2S? A lucky person finds @yvolk issue #499 to analyse. OAuth2? Webfinger? NodeInfo? Plan some days to do your spikes…

Much of the knowledge remains stuck in github issues, matrix chat rooms, or even in this forum like with e.g. the Groups implementation (still ongoing, but will the results be summarized somewhere?).

Ongoing developments regarding the future of the specs are even harder to come by. Extensibility, shards, capabilities, encryption, forgefed, etc. etc. Seems to me that lots of the discussion is not easy to come by for the (casually) interested, unless one dedicates to become deeply involved.

What is needed is a one-stop-shop to drill-down into all of this. A place that is maintained and up-to-date. A hard thing, because there is lotsa work involved.

Current efforts

On SocialHub @nedjo started the Guide for new ActivityPub implementers wiki post (to which I make occasional updates) which is slated to become part (presumably) of fediverse.rocks once/if this site gets an overhaul. ActivityPub Rocks has best SEO for ‘ActivityPub’ search term (#1 on DDG, #4 on Google) and it is a pity that the site looks so… bare.

I recently started helping out with improving the fediverse wiki (research area for fediverse.party). Fediverse Party has best SEO for ‘Fediverse’ search term (# 1 on DDG and Google) and is great for fediverse end-users with their nice UX and all. I opened an issue proposing for fediverse.party to also target developers and extend the site accordingly.

Either of these two, or both, could be top-level homes for AP/Fediverse developers.

WDYT?

I am not an ActivityPub expert (but a big fediverse advocate, and very concerned humanetech proponent). I am sure y’all have concrete plans already, better ideas than me, and I’d love to hear your opinions and ideas

[birdsofpraise]

I think a huge help would be more low-level libraries that deal with just the protocol stuff. Generating and parsing ap jsonld, signing requests, etc.

Also guides should mention how RDF plays into it all.

Finally it would be fantastic if we could develop some shared ux/ui for common elements and tasks. Developers are traditionally not great at ux and for decentralised services its particularly difficult

[aschrijver]

Yes, thank you. I heartily agree with these ideas as very welcome additions to the ecosystem, and some of these are being worked on or already exist (like @cjs #software:go-fed for Go programmers and others on the AP watchlist). But those are ‘tech tracks’ within the community. I created this topic more for the community-building + organization to make all these efforts easily discoverable and consumable.

[cjs]

Maybe Relevant: About 3 weeks ago started scoping out the idea of curating a library of sorts posts to attempt to mirror the informative long-form content that has already been written and hosting it at library.activitypub.dev with a very simple organizational structure. It isn’t just meant for AP technical details but also Fediverse culture as well, because I think it is important for folks that are non-technical to have a voice as well. This only partially addresses the problem: the scope really is just “digital library” and not meant to be any sort of organizational body (though it could help inform such a body).

Then there’s the activitypub.dev domain itself. I have no idea what to do with it, because I haven’t had time to think about it & plan it (let alone execute the plan).

I can bullshit a vision and roles on the spot just to get the conversation going starting from somewhere:

Task Force Tasty 'Taters: build and maintain a community-run Fediverse repository of information

Code Name	General Goal	Tasks
Static Site Sauerkrauts	They’re in charge of running the static site	Build or use existing static site infra, maintain it day-to-day
Content Outline Corncob	They’re coordinating the site’s content	Outlines and organizes the site’s content layout
Design Dumplings	They’re in charge of the site experience	Making the site look less like something from 1998
Author Avocados	They author the content	They do the research required to author the content that Corncob outlined

I think one view of our core problem could be that we are too many technical folks focused on doing too many technical things, and don’t have enough traction with the wider Fediverse community to have an encouraging story that inspires volunteers.

[aschrijver]

Hmm, yes interesting, @cjs. Crossposting from a comment I just made on the fediverse.party issue:

---

Imho for the fediverse as a whole it is best if just one site is the authoritative go-to location for AP developers. This gives the most likely chance there are enough contributors to keep things up-to-date.

Maybe (just brainstorming) the separation of concerns could be:

• fediverse.party: The authoritative Fediverse directory for end-users and techies (given the tech metrics in directory entries).
• activitypub.dev: The authoritative AP/Fediverse in-depth development guide and resource pointers.
• activitypub.rocks: The authoritative AP/Fediverse reference for specifications and future versions/extensions thereof.

---

Note: This related to your top-level domain --> dev-specific audience
(BTW… love Sauerkraut )

For fediverse.party I was thinking of using a Just The Docs Jekyll theme so content creation is pure markdown that anyone can just PR to, and is then auto-published by Github Pages. I’d simplify by creating just 2 teams, one for ‘Site maintainers’ and one for ‘Content creators’ both of them where you give frequent contributors the extra privilege to become members (an incentive to stay committed). Then create one project/board mostly for content creation tasks.

@cjs

[Re:Library] It isn’t just meant for AP technical details but also Fediverse culture as well, because I think it is important for folks that are non-technical to have a voice as well.

I wonder about your mixing of tech-related and non-tech cultural aspects of fediverse. Separation-of-concern wise I’d say there is a niche for the latter to be a separate thing altogether. Even though I follow mostly techies with @humanetech I still see complaints about the geeky atmosphere on fedi, made by non-technical users.

If the fediverse grows in popularity like we want it to, then the majority of people do not care about all the technical stuff, and those who do will find it easy to get tech in their circles and do a deep-dive.

@cjs

I think one view of our core problem could be that we are too many technical folks focused on doing too many technical things, and don’t have enough traction with the wider Fediverse community to have an encouraging story that inspires volunteers.

While this is true, I don’t think you find it easier to get volunteers in a mixed tech/non-tech content environment. Not non-technical volunteers at least. This assumes they care about this mix, while for most non-techies the language we speak is absolutely archaic and obscure (this risks the same pitfall as when we think users like our developer-friendly UI).

BUT… I am highly in favour of targeting a much broader set of technical expertises than this community currently does. UX + interaction designers, project managers, product owners, architects, QA’s, DevOps, (maybe) domain experts, what-have-you… And also different levels of expertise, like e.g. targeting the newbies in these fields more explicitly.

What many AP experts maybe do not realize is that their casual discussions are really high-level for the uninitiated techie (the majority of tech world, many of whom don’t even know about the Fediverse yet). “What the hell are they talking about? I’ll not chime in, but maybe if there’s a summary afterwards I can see if it was useful to me.”

Marketing types love to talk about the “user’s journey”. Well, I guess, this is about the developer’s journey into the realms of AP and very much a part of the onboarding process that is needed, imho.

[cjs]

Appreciate the feedback! I like the idea of your separation of concerns for the 3 different domains. As for the team names… I was hungry and feeling alliterative at the time.

I think the second half of your comments risks derailing perhaps your intended discussion. I’ll keep this short and am happy to discuss in another thread. The related “digital library” idea is intended to solve an adjacent but very different kind of problem than “dev community needs to create resources for itself”: the fediverse community needs to create resources for the fediverse community. A very real failure mode we’ve had is that the non-technical voices (or the technical voices advocating for the non-technical voices) have not been able to successfully bridge over to the technical side and enact proactive change, or have been incredibly slow to, to the point where devs and harassed users alike have quit being Fedi devs or left the Fediverse entirely. I’m intending to have the digital library purposefully break down these separations to reduce the risk that folks feel like they are shouting into a void unheard or are talking to brick walls.

…back on topic of getting better dev resources. If we want direct action, then hopefully someone feels empowered to just “sit down and take charge”. Reach out to peers, advertise “hey I’m going to organize this thing and need help”, have an initial (but malleable to input) vision, maybe find some extra pairs of hands here and there, and self-organize. They should feel happy at refuting “who put you in charge” with “well its been 2 years and no one else has shown up but me”. I think that’s kind of how this socialhub came about. It’s certainly how the unofficial test suite came about. I’m not saying this is the best way, and it certainly requires a lot of charisma / energy of one individual to push a wet noodle.

[how]

Thank you for starting this discussion. I would surely appreciate that the SocialHub becomes friendlier not only to new developers but also to community members so that developers and users can have stronger ties: this is one of the goals of #fediversity – which the fediverse.party people could host (see @fediversity.hosts).

Discourse can be used across static sites and offers excellent told for collective knowledge building. I would be happy to integrate with some dedicated matrix rooms as well.

More later…

[aschrijver]

@cjs

If we want direct action, then hopefully someone feels empowered to just “sit down and take charge”.

That would be the ideal. Next best is the more informal, slower process of gauging interest among current devs, collecting ideas, elaborating, etc. all in various SocialHub discussion threads. There could be a separate sub-category for this under ‘Community’, maybe ‘Developers’ or ‘Developer-onboarding’ or whatever (@how?). And might have a wiki post where we collect the results and crowdsource the draft of a plan.

These discussions can then be used to prepare input for the upcoming AP Conf which has I believe a number of related BoF’s and events (i.e. “Scaling Up Cooperation”), which could be made more productive based on this preparation? @Sebastian?

@how

Discourse can be used across static sites and offers excellent told for collective knowledge building. I would be happy to integrate with some dedicated matrix rooms as well.

It would be great if discussions were aggregated somewhere and/or to be accessible from a single access point. With the static site integration do you mean adding comment threads to blogs/articles, which also end up on the forum (I use this on our humanetech forum, but only for a single site)?

[luceos]

@aschrijver

I recently started helping out with improving the fediverse wiki

I see mention of a Wiki and was hoping that your fears, Arnold, could be alleviated with such a wiki. The link is dead though What is anno 2023 the goto place for a concise summary of all elements involved with federation according to the specs you are working on?

[aschrijver]

Things are fragmented I’m afraid, Daniël. There’s many independent initiatives, and more starting every day. This SocialHub forum in itself constitutes a huge archive (but chaotic, as they are discussions). The FEP process is most organized, and the W3C SocialCG is being revived, right now. I am hoping people are open to bring more cohesion into all this.

The SocialCG mailing list is a good one to subscribe to. And the Fediverse Developers chatroom on Matrix. That wiki is long dead, and the lists moved to the fediverse organization on Codeberg. Also note the pinned Guide for new ActivityPub implementers … this is a wiki too, that anyone can update and help improve.