Development experience for third party apps

[marcelklehr]

Hello,

I'd like to talk about something that has me frustrated for a while. The nextcloud ecosystem is dependent on third party developers integrating new fabulous applications into the platform and some people actually want to do that. However, at least for me personally, the development experience leaves a lot to be desired. The documentation is the bare minimum and sometimes even outdated while large chunks of new developments in core are simply not accessible to third party developers when just looking at the documentation. People are expected, it seems, to dig through the API docs and make sense of the interfaces on their own. This is a problem in my opinion.

I feel like at the very least there needs to be:

• a thorough refactoring of the app dev manual so that it covers not only the PHP Controller infrastructure, but also caching, system tags, collections, client-side APIs, the vue ecosystem and possibly more that I haven't heard of yet
• some kind of newsletter/mailing list/forum where new developments in core are announced to developers (preferably ahead of time) in order to adopt and integrate them
• a place (online) for developers to share expertise and discuss problems

[Spartachetto]

Even if I am not a developer, I had the same impression trying to help with the issue #13330 .

It seems that integrating system tags into an app is not superintuitive.

[ChristophWurst]

Thanks so much for bringing this up!

This is something that also bothers me because I see that it doesn't only affect third party devs but also core developers sometimes.

We definitely should try to be better with documentation. The dev docs should cover all the public APIs and show examples of how to use them. It's easier said than done, though, so any help is appreciated as we don't have a dedicated person keeping the docs up to date.

For changes I like the format of Laravel: https://laravel.com/docs/5.6/upgrade. It's basically a prose version of the "Critical changes for devs" issues with a bit more guidance on how to migrate away from deprecated APIs or how to adapt to new ones.

For the js APIs I opened #15932, where we now have lots of new js packages that I hope are more straight forward to use than the hard to discover global variables/functions used in the past. I'm trying to document the usage of these packages as good as possible. Here is an example: https://nextcloud.github.io/nextcloud-event-bus/. Of course this also kinda falls short as nothing links to it. So as long as that stays undiscovered, it doesn't matter how good the docs are. I have a task on my todo list to add a page about js APIs to the dev manual linking to the specific packages.

[ChristophWurst]

a place (online) for developers to share expertise and discuss problems

That would be https://help.nextcloud.com/c/dev

[tobiasKaminsky]

as we don't have a dedicated person keeping the docs up to date.

Those who create/add/modify API, should then also adjust it in documentation.
Not sure how we can enforce this via some tools?

[noci2012]

And a valid & working demo of how to use it in stead of a crammed together hotch potch half baked non working example that could never have worked in the documentation. The provided example should also get ported then dev's can compare changes if needed there as well.

[Spartachetto]

@ChristophWurst here is a discussion on this topic in that section of help.nextcloud: https://help.nextcloud.com/t/state-of-app-development/63670

As you can see similar problems are raised and nobody is answering...
I understand the added workload, no idea if Nextcloud could use some automation to deal with this problem.

[noci2012]

@ChristophWurst: in addition:

We definitely should try to be better with documentation. The dev docs should cover all the public APIs and show examples of how to use them. It's easier said than done, though, so any help is appreciated as we don't have a dedicated person keeping the docs up to date.

The current documentation is incomprehensible and in consistent. Asking "new" developers to update it will probably not help there is more needed than "just" a few changes / clarifications.
The current documentation resembles a list of methods & parameters. I guess a howto / whento / whydo type of manual is needed. Something a programmer can start on page 1 and work through to get a working plugin.