Kube & Sink docs at api.kde.org/doc still wanted/needed?

Sat May 23 15:44:24 BST 2020

On Saturday, 23 May 2020 13:36:11 CEST you wrote:
> To avoid misunderstandings, let me start with a disclaimer:
> No bad feelings here myself to anyone, also neutral to actual projects and 
> where they should live and with whom cooperate.
> All I care for are synergy effects and getting things cleaned up and fixed and 
> properly done, without resources wasted and pseudo activities happening :)

That's appreciated, let's be constructive about it =)

> 
> Am Freitag, 22. Mai 2020, 14:07:02 CEST schrieb Christian Mollekopf:
> > On Friday, 22 May 2020 12:23:20 CEST you wrote:
> > > doing some housekeeping on the server behind api.kde.org it was found to
> > > surprise to some that the nightly script is spending cpu, i/o & storage
> > > resources each day on generating some documentation for Kube & Sink, with
> > > the result available on
> > > 
> > >     https://api.kde.org/doc/kube
> > >     https://api.kde.org/doc/sink
> > > 
> > > At least for Kube the official documentaion as linked from
> > > kube-project.com
> > > seems to be on https://kube.readthedocs.io though, not api.kde.org/doc.
> > > 
> > > So is that documentation generated and made available on api.kde.org/doc
> > > still wanted, or could we remove it already?
> > 
> > Whatever is easier for the time being.
> 
> For me it is not about what is easier, but what makes sense. 
> 
> > It's not API documentation so it was
> > always a special case,
> 
> Yes, reading the content it seems more "About project" material to me, not 
> targeting developer end users, like api.kde.org does, but rather developers 
> working on sink & kube itself.
> 
> Why has that been located on api.kde.org at all, instead of getting an own 
> server with own subdomain? Smells a bit like "too little love" to me :(

I think it ended originally up there because it was an easy solution and I agree it's not necessarily the best place in the long run.

> More perfect would have been using the doc system that other KDE projects use 
> for internal organisation, which is community.kde.org wiki. Yet, I see why one 
> would like a non-wiki-but-run-by-content-from-git solution, but that should be 
> done in cooperation with other KDE projects who also would prefer such a 
> thing, so there would be a proper server name/location and also things 
> properly linked from everywhere. After all synergy is one of the motivations 
> for having something like the KDE organization, so any server systems are only 
> setup/administrated once, but used by many and with some consistency.

Wiki would have been an alternative that I chose not to use, and to some extent mkdocs certainly has been an experiment.
As I know I'm straying from the usual path, I'm not expecting for there to be a standard solution for this kind of documentation but I suspect gitlab comes with some improvements in that regards already (with markdown support we're pretty much there I suppose).

> > and I started using readthedocs.io at some point
> > because publishing repeatedly broke and I didn't have a direct way to fix
> > it myself.
> 
> Why did you not manage to get that direct way? And why was the old system not 
> turned down at the time when you switched? Again I smell "too little love" :(
> Or is this about "easiest"? :) Being part of a big organisation does not come 
> for free with all the goodies only, of course it also comes with bureaucracy 
> and dealing with people whose first priority is not your own project. And 
> having to contribute to some common goods which not fully serve own needs.
> Please do that trade-off, because being part of an organization also means you 
> are the organization.

> Also disappointed to see that kube.kde.org ATM forwards out of KDE spheres to 
> kube-project.com as homepage, which is not a KDE-run server by what who-is 
> tells me.
> How much do sink & kube want to be real KDE projects? Any chance you could get 
> off your fence position and do a jump to either side in the near future? (KDE 
> one preferred for assumed synergy effects) 

While I think I understand where you are coming from, I think we have very different concepts of a "real KDE project" and there is no intention of positioning Kube as a "realer" KDE project.

I'm happy to elaborate if necessary in a separate exchange, for now I don't intend to change this. Let's assume that I have reasons for doings things the way they are done (and I'm sure a healthy debate can be had over the validity of those reasons), and from my perspective I'm not asking for much besides a git repository, so even if there is room for improvement, there isn't much harm done IMO. But I understand that the are certainly downsides to this approach, such as not all KDE projects being uniform, which adds friction in places.

> > > Be aware that the current legacy system behind api.kde.org is in
> > > maintenance mode and in some months(?) hopefully replaced by some new
> > > system, so you want to make sure any perhaps existing interest in future
> > > documentation generation in that new system is covered. See
> > > https://phabricator.kde.org/T12004
> > Once that new system is up and running we can look at it again,
> > from the ticket it seems the usecase of mkdocs has been taken into account,
> > which should be all that is necessary I think.
> 
> Not part of that initiative (for now), but from reading the task I think that 
> while the use of mkdocs has been listed there as part of analysis of old 
> api.kde.org system setup, it is unclear yet why it is used and how much sense 
> it makes. Also note there is an open question to you:
> https://phabricator.kde.org/T12004#208822
> 

Thanks, for the hint, hadn't noticed.

> By what I read and saw so far, I am rather decided to propose to just shut 
> down doc generation for kube & sink on api.kde.org/doc, given I sense no 
> serious interest in those docs at that place and them also being misplaced 
> under that domain. With kube.kde.org redirecting to kube-project.com it also 
> seems to me that the cannot-decide-to-be-a-real-kde-project state is accepted 
> state by those who incubated kube & sink into KDE spheres, and also not 
> motivated myself to pull or push someone who does not have intrinsic 
> motivation to move themselves and just would need assistance for that. All 
> happy to help (where I can, no admin myself) those who have intrinsic 
> motivation and show active interest though :)
> 
> So unless I hear some objection, would be coordinating with sysadmin the 
> disabling of the generation & serving of the about-project docs for kube & 
> sink at api.kde.org/doc upcoming WE, May 30th/31st.

No objection from my side.

Thanks,
Christian