Better documentation for GTK request

Community
1

A few days ago I have stumbled upon a talk given by Subsurface developer Dirk Hohndel. I think that most of critics to GTK features were fixed, but unfortunately I can’t disagree about the other part.

The Gnome/GTK community needs to give better support to documentation, introduction material, tutorials and examples. Most of people that start coding an application didn’t start as bright coders, they evolve as time passes by and the application itself also evolves.

Not to mention that he and his project partner are not newbies in coding. He and his partner are famous for a relevant piece of software (or two).

I sadly had to say I felt the same in many situation of my struggle to learn how to handle Glib/Gtk/GObject. Either the documentation or the community were lacking in this aspect.

I never coded in QT (since I don’t like C++), but as he says the QT developers and community were much more friendly and embraced him and his project in the first steps of migration from GTK2 to QT3.

Last but not least, I can’t say how much I enjoy GNOME and GTK applications, guidelines and philosophy. My desktop was always GNOME since 1.0. And I have tried many times to understand how to code using GLib/GObject/GTK. I will keep trying.

If someone want to check the video, link below

2 Likes
2

Reference to the lacking documentation or community please?

3

By definition, is impossible to make references to something that do not exist. But I can try to give some examples.

There is no introductory material explaining how to use GObject, the same applies to Glib and GTK. Almost all documentation is only related to C library. How can I create a GObject and use instrospection to use it from Python?

I could not find any documentation in how to use Gnome-Builder to create and keep an application running including: how the SDKs worked, how to redistribute the application, how to install a application in OS inside the gnome-builder. Those things seems stupid for those who already know but are a huge problem to someone that do not know how to do correctly.

In some cases I could not accomplish some tasks (I cannot point exactly any right now), and could not find a way to solve my issue, either in documentation or by talking with community (this forum included).

Also I could not find guidelines to build interfaces, for example how to build a modern gnome application, how make it behave as a good application, what can you make to create a interface that matches the gnome. Most of time when I tried to reproduce some application (for example the bar on top of many gnome applications) I just could not do it, because it just do not looks similar, or maybe rendering bugs, or some flag not correctly set in glade. When talking to the community I just got the answer read the source code. Is that ok. In certain level it is, but a more gentle approach should exist if we intend to make other people to use your libraries.

The fact is, I have gave up to code in GTK/GLIb/GObject at least for now, I’m slightly demotivated by all those issues (not that makes any difference). Therefore I decided to focus in my PhD (have to study other stuff as meta-heuristics and such).

If someone as the developers of Subsurface were not able to do what they meant to do with their abilities, what a multitude of willing to be developers can do?

I just submitted this post because I have (as I said), stumbled over this talk, and at least for me, it makes all sense.

Please bear with me, isn’t a trolling, is just to makes you guys notice that maybe (just maybe) there is some issues to be enhanced.

1 Like
4

Just to make things more clear, seems QT community (because Trolltech was a company selling a toolkit) were much more friendlier and helpful with their newcomers.

By experience I could tell that Matlab is more used than Python (in academic community) exaclty by the same reason, if you check matlab official forums there are a large ammount of examples, code that solve someone problem. After you get more experienced in the tool those posts seems to look stupid, but for sure they can help the newcomers and as they evolve they will be able to put together many different parts to build their own application and after some time, be able to improve. (but that is not necessary).

PS: Im not a Matlab user, I got the same complain from a friend of mine that could not find good material from Python (years ago), of course that changed in the last 4 years in Scientific Python Community. Fortunately he had someone else that knew how to code a simple Python code to help him in first steps.

PS2: I have tried to create a local study group in my local community with no success, have invited local developers and made a open invitation but nobody show up.

5

I have to agree with you in most points, but saying it loud may make it even worse.

The positive side of GTK is that API documentation is not bad, and that there are bindings to many languages.

Community? E. Bassi is the community, partly supported by a few people like Mr Baedert. And I think there is Mr Larsen, ebassi called him maintainer. And there is the gnome foundation, and there is https://planet.gnome.org/ I have to admit that I have no idea what that people do with or for GTK/Gnome.

I do google and github search from time to time to looks for new gtk projects or people using GTK seriously. Found no results – but I know the https://github.com/horizon-eda/horizon project developed by a far friend of mine with GTKmm. A great guy and a great project, but that is the only one, all the other people I know are not using GTK. They use Qt, web apps and mobile only. You may know that I have spend much time in the Nim GTK bindings, which currently only very few people are using. People have asked me for extended tutorials, in the shape of the GTK2 book of A. Krause and a large collection of well documented, up to date examples. We do not have this, for no language. Well there are some docs for C, Python, D. Maybe that would be even enough with a large active community.

So what can we do? Can we assume someone to write a new book, when it is clear that the book would have less than 100 readers if it is free, and maybe 20 readers if it is sold? I don’t think so. What we can do is writing well documented medium size examples, and clear, up to date advanced tutorials. Don Torront tried that for D lang, maybe a bit too fancy and verbose, with concentration on the basic GTK2 stuff unfortunately. C. Eric Cashon gave some nice C example here in the last months. And well, I gave some Nim examples at https://github.com/StefanSalewski/gintro.

1 Like
6

Not saying also will not get anywhere. But my intention was not bash against GNOME/GTK project and members.

Seems like we have a self-fulfilling prophecy here, we don’t have docs because we don’t have developers and we don’t have developers because we don’t have docs.

I don’t think a book is the solution (by the reasons you have explained), besides that tech books get outdated REALLY fast, but I think that focusing more in small stuff online, one by one is the key.

Instead a hack fest why not a Spread fest? Why not get everyone involved in a week to explain some BASICS of gnome/gtk/gobject/glib/glade/builder? Put those on internet. Talk to others not among ourselves. Hack your own gnome app. Why not promote local users groups of developers (instead only users). Those are just ideas, but I think if we globally create a calendar to Spread Coding week, we can get some people getting involved.

We can easily look for mini-courses on python scikit learn classes online, not necessarily Udacity paid courses, there are many 4 hours speeches with some code developing in doing basic things as using machine learning (trending right now).

As I said before, I tried to create a study group here where I live. I have spoken with local gnome group (they are endorsed by Gnome Foundation) but unfortunately nobody attended to the call. I have university that can help, we have computers, rooms, projectors, white boards that could held a meeting like these (to teach newcomers to code using GTK stuff).

Hope we can get somewhere.

1 Like
7

That sounds like you only interact with the community through Discourse. There are many more people on IRC.

8

No, I was subscribed to mailing lists gtk-list, gtk-app-devel and gtk-gedit for the last 10 years. Was even more dead than Discourse.

And I tried IRC some years ago – connected for maybe 30 minutes, there was no activity, so I never tried again. Well I may try IRC again – unfortunately I am not a native english speaker, so writing fast is not that easy for me, and generally I like well formulated questions and answers better, so I would prefer mailing lists, newsgroups or forum.

Is there a IRC log for GTK? Some other projects have it, so one can see what is going on before connecting. Like https://irclogs.nim-lang.org/

9

While I enjoy IRC, people will get upset if you ask too much, or do some questions that they thing are stupid. That inhibit more questions and often lead the the person leave the community. Again I’m talking about my personal experience, not only in #GTK channel.

Salman Khan, famous for your video tutorials in math, physics then everything else (that lead to Khan Academy), said once, he started to make the videos to allow his cousins to be able to replay his explanation as many times they want, because otherwise, he would get upset and his cousins too.

A IRC channel is good for a chat or to solve some spot issues, but not for teaching or learning. People get upset, also as Stefan said, you can go there, make a question, wait for hours and be completely and utterly ignored. Because everyone is AFK, because nobody want to answer that, or just because nobody read the message.

@baedert : I started this post indeed. I’m not hardcore C coder. I can do some code better than most of people that I know in academia, I can say that in academia I’m a top 1% best coder, but im pretty unimpressive when compared with most of people hanging around on IRC.

Some times my questions make them upset. Let me tell a history: I remember once, I was coding a full week in python, and I submited a question regarding a C code I had testing without any success. The code just didn’t compiled. I posted it on pastebin (or some other place). The answer was:

  • First: learn how to code in C.

Wow. What? My data structures are pretty good. I have some useful skills. My code is most of time 100% clean in Valgrind (and I’m proud of that). I got very upset with that comment.

Then I checked my code. Could not figure out what was wrong, nobody answered me what was the problem.

After taking a break I noticed. I completely missed the int main(int argc, char *argv[]) {}. I just coded as I did in Python, no main function. (and that was not a library)

That was silly, but also, is a kind of symptom about people in IRC getting upset with your questions.

10

Yes, you’ll have to wait longer on IRC for a reply. People will either take longer or just by in a different time zone anyway.

I am personally way more likely to quickly answer a question on IRC because people will have smaller questions that I don’t have to read through several paragraphs of text and hundreds of lines of code for.

11

It seems like you’re probably going to have better luck requesting tutorials or documentation for specific topics you think are lacking. Unfortunately “fix all the documentation” isn’t either an actionable or reasonable request, unless you are proposing an initiative that you are willing to spearhead with work you plan to do.

Good examples of this actually being accomplished are @StefanSalewski with the Nim language and @rontarrant with the D language. Personally, I’ve spent some amount of time contributing documentation and tutorials for GJS. Be assured, this work does not come easily or quickly and ultimately only happens when someone steps up to do it.

I understand your intention is not to attack anyone, but I’d like to point out how discouraging it is to be generalized as unhelpful and unapproachable based on one or two interactions you have had. That certainly wasn’t my experience as a new developer nor is it how I see new developers treated on IRC or elsewhere.

1 Like
12

Let’s also not forget a key point of Dirk’s talk: Linus was asking questions about GTK application development on Google Plus, a place where only a handful of GTK developers ever looked. The self-selecting circle of possible responders, coupled with Linus’s well-known “acerbic” style and his general Dunning-Krugerness about userspace/GUI application development, yielded very poor responses. So, when somebody showed up and offered to rewrite his toy application using Qt, he achieved his goal of not having to care any more.

2 Likes
13

To complete the story, in a sense, there was a follow-up talk at LCA 2019: Desktop to Mobile - Developing for Multiple Platforms without Losing Your Mind. In this talk the complaints were about Kirigami and QML.

If anything, it says more about the difficulties that experienced developers in one field have when moving to another than it does about the technologies themselves – there is almost an expectation that it’s just software, so they can just pick up the tools and run with them.

Having said that, we should pay some attention to this kind of feedback even when it is delivered in a provocative way because it does say something about the onboarding experience of new users. And we can enjoy watching opinionated developers suffer a little as they are forced to go back to basics and be newbies all over again. :wink:

14

Which is why GNOME has a whole newcomers initiative, coupled with integration within GNOME Builder; documentation bugs get fixed pretty quickly; we keep asking for new material to put on the developers portal, including a permanently open thread on Discourse; and we have a full rework of the GTK website in the pipeline.

Yes, we listen to pain points and suggestions from developers—both newcomers and experienced alike. All it takes is not to be an asshole about it. I have better things to do with my time—both paid and otherwise—than listening in to “provocative” crap that is virtually indistinguishable from a Dunning-Kruger-driven rant.

1 Like
15

While there is always room for improvement, GTK is well documented by comparison to many parts of linux. Qt does have more comprehensive documentation but it would need to have, the monolithic class tree it gets from being based in C++ makes it almost impossible to use any sub set. You can also see that in the number of language bindings each system has, Qt is obviously harder to work with in that sense.

So while its fair to say the documentation could be better, I think its pretty good now and forums like this discord is very effective at handling any gaps. I say this while current trying to code something for PulseAudio and fighting with real flaws in the documentation. There is something I want to do which I can find no clue about at all. I’m not even sure if its the right thing to do given the function I want.

16

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.