Let me share my opinion on some of the topics I have read here.
In general, I consent that the documentation needs improvement. However, I think we need a broader style. Currently, we have a basic API reference and a more-or-less walkthrough for a minimalistic app. What I am missing:
- A general overview of the dev process for complete newbies (get started with web development in 10 minutes)
- Detailed architectural descriptions on the building blocks of the NC backend (how are the gears mesh )
- Dedicated chapters related to security-relevant topics: What are the notions? What is the motivation behind certain structures?
- A complete API reference with all classes/interfaces in
\OCP well-defined and documented.
- There should be different walkthroughs for different levels from beginner to advanced also with different reading speeds and/or cross-links. Keep in mind to have devs from foreign languages but with architecture experience
- Give the app developers a space to share common APIs to simplify common work. Also, best practices should be defined before.
Adding more documentation might make restructuring the docs important. Currently, there is a category Digging Deeper that is sort of catch-all. This might need a break-apart.
One could consider creating e.g. screencasts and publishing them. This will attend to another audience then just plain text. Example form joomla with youtube video.
I know this is a hell of work to carry out good videos but this might be a community approach at best. But then, it needs backup by the core team to for example not make significant errors or document something in detail that is due to change soon.
One thing, I want to oppose here on the thread a bit is the request for more abstractions. Yes, the NC cure team could implement a general way to exchange data between the backend and frontend. Up to a certain level, this is a good idea. However, this should be the second step.
I have been developing with Joomla and there is a lot more of this automagical shā¦ going on. Either you know this and learn it by heart or you are lost. You can read other peopleās code but you have a hard time getting your things to work. This is one reason, I abandoned my recent project and decided to do it in the NC core. The documentation and code of the NC are way cleaner. (This is my personal opinion. You can argue but just have a look at their kernel.)
It is true, you can get results faster. But once you leave the basic paths you are mainly lost. You have to do everything manually. There is no Symfony framework having your back and helping with e.g. class loading. Itās on you, mainly.
Long story short: I think the current structure is a good one. You can learn it. You can use it. Yes, you need documentation for it.
Now comes the second step: You could add some abstractions on top of that as an addon to simplify life with typical problems. But this should not render the basic skills second-level citizens. In contrast, this should be marked as such. Devs are responsible for their decision on what interface might be better suited.
There have been requests for Mattermost, Discord, etc here. I do not see fit for these. What is the benefit over the forum here? All of them provide support for markdown, threads, etc. What is the significant difference?
If there is, I might change my mind. I personally prefer Mattermost over discourse but this is just personal taste.
Adding another channel might split the community even further. ATM we have a Matrix channel, this forum, the GitHub discussions/issues, and the various chat rooms on the official server. Did I miss something? The more options we have the more valuable experienced developers need to spread.
I am even considering if the NC talk rooms are a good option for the public community. These are only reachable using a public link. This is not ideal for public community building. No notifications, no last-read state, etc.
After the initial post, I decided to go through some of the topics here on the forum and help out if I can. I see a small part of the responsibility for this situation also with us community members. There are many seeking advice and do not get it. Then, if these devs accumulate their personal knowledge, they do not share it. Voila, you have a vicious circle. I can only pledge: All devs keep a look on the new topics and try to help newcomers as best as you can.
Some things can be done centrally but need documentation before being implemented. For example, it took me quite some time to set up a DevOps system for automated tests to run on the dev machine with an arbitrary PHP version/DB system involved with exactly the same configuration during CI. It is a lengthy python script that might easily be adopted for general use.
It took me quite some time to get it working and Iād like to share it with other authors. But, it will require some setup and documentation on how to integrate it. Here is also the question(probably @Daphne knows who to address), how such contributions can be handled.
What I am missing most is access to the more/most experienced developers. I had quite some time questions related to the core and its behavior. In the end, I debugged the server instead of writing my own app. This is not time-efficient.
In another project (https://octoprint.org/) there is a monthly (?) FAQ over a live video stream with the main developer. It is sort of a Ask Me Anything session (you can provide questions before and these are addressed one by one by her. The session is live for Patreon supporters and the recording is published afterward for all interested. Tina was awarded for a very strong community binding.
Could we do something similar? Maybe even from the community, a few experienced devs are there for questions. These do not need all to be core dev members. But it would be nice if there was at least access to the core team. You could combine this with some sort of badge/tier that must be affordable. These are in fact your future senior devs!
Some other point that the NC company could provide is infrastructure. For example, for devs it can be interesting to extract some sort of telemetry data. For example: is it safe to drop support for NC 21 in my app without losing too many users? What apps are installed alongside the app?
Maybe there are dedicated questions the app devs might ask more specifically (How many recipes are registered per user avg/max?)
This could be extended to other services as well. Example: We are discussing an AI-based detection of strings that needs training data. It would be useful to let the users voluntarily upload data to train/enhance the classifier. But this is rather advanced.
One big time-eater is requesting the required information for bug issues. Sometimes it is hard for the users to collect the required information. An app to open new issues might help them.
Sorry for the very long post.
)
