Update link to GJS documentation
liberforce opened this issue · comments
The GJS documentation has been updated a while ago, so the current link in README.md is broken. Here's the right one:
http://devdocs.baznga.org/
This was anounced by GJS maintainer a while ago: https://ptomato.wordpress.com/2017/05/22/the-gjs-documentation-is-back/
Removing mention of it being unmaintained would be nice too :)
Thanks for the info, updated!
Please reopen. You somehow forgot to link "Gjs documentation" to http://devdocs.baznga.org/ in your changes. Direct linking is better than indirect, as people won't necessarily click on a link just named "since appeared" to get the information.
I did not forget but consciously avoided linking directly to that site, because frankly, I do not consider it worth linking to:
-
The incomprehensible domain "baznga.org" is not in any obvious way affiliated with the GNOME project. Opening the TLD http://baznga.org/ in a browser gives a timeout. I have no way of knowing what that URL will point to a year from now.
-
Likewise, on the page itself, there is no author information, just a hard-to-find link to an obscure GitHub repository that again doesn't mention GNOME anywhere in the README.
-
Documentation search doesn't actually work when you load the page because all the GNOME packages (you know, the ones I actually came for) are disabled by default. This was reported in a comment on the original blog post nearly 18 months ago and still hasn't been resolved. The issue tracker for the aforementioned repository shows several year-old open issues and not a single closed one.
I therefore feel forced to conclude that this new documentation, like the previous one, is again semi-official at best, and borderline unmaintained. I fully expect it to eventually be replaced by yet another well-meant effort hosted at whatever.org. I have no interest in keeping up with the latest link just because after 8 years, GNOME still can't be bothered to host documentation for their own product on their own domain.
But of course, I am interested in keeping the information in the Argos README relevant. As you have kindly pointed out, that particular paragraph in the "Acknowledgments" section, while perfectly accurate at the time of writing, had since become outdated. It is now once again perfectly accurate as of today. I chose to link to the blog post because it shows that indeed, the new documentation only appeared in May 2017, which is basically what that paragraph talks about.
As far as Argos is concerned, this settles the matter. Please feel free to open another issue if you think that the README still contains inaccurate or outdated information.
TL;DR
The blog link is valuable, but less that the website hosting the docs. People change blogs, and trying to find a link to a dead blog post pointing to another website is harder than finding the new location of a direct link.
Here's for more.
I totally agree there are problems. The domain names used for some documentation like http://devdocs.baznga.org/ or https://lazka.github.io/pgi-docs/ don't look like official sources, and this is a problem that somehow hasn't been adressed for years by the GNOME community.
However:
The incomprehensible domain "baznga.org" is not in any obvious way affiliated with the GNOME project.
Likewise, on the page itself, there is no author information, just a hard-to-find link to an obscure GitHub repository that again doesn't mention GNOME anywhere in the README.
Nor the blog could you say. But is the personal blog of Philip Chimento, aka ptomato. It's agregated on https://planet.gnome.org (as seen in the feeds). His nickname and real name are in that github account, in the URL of that blog post, and in several other places. The guy is the maintainer of Gjs, gave talks at GUADEC, and is since this summer in the GNOME Foundation Board of Directors. I also fail to see how talking about GNOME in the README would make the repo less "obscure", or more trustful.
The http://devdocs.baznga.org/ page says right in the first line "This is the API documentation for writing GNOME applications in JavaScript". Then on that very same page, you have:
- DevDocs is free and open source. This is a modified version.
…and the link for the "modified version" text points to that "obscure repo". This is probably not the chain of trust you expected, and I agree that's probably not the best experience, but that's the current situation and seems like an improvement over the past one.
Documentation search doesn't actually work when you load the page because all the GNOME packages (you know, the ones I actually came for) are disabled by default. This was reported in a comment on the original blog post nearly 18 months ago and still hasn't been resolved.
I don't see the point, this is a minor issue. As the maintainer said "Feel free to report a bug or even better, submit a pull request". Sure, this is not perfect and can be improved, but this is Free Software: there's a lot to do, few people, and only 24 hours in a day.
The issue tracker for the aforementioned repository shows several year-old open issues and not a single closed one.
The oldest issue is from 2017, 18th of June. That's 1 year and 4 months, and the issue was opened by the maintainer himself as a reminder. Again, yes, the situation could be improved, and again, patches are welcome.
Your own issue tracker has issues more than a year old for around 600 lines of js, and that's fine. Gjs is around 40000 lines of C++ and javascript. AFAIK Philip is the only maintainer and has multiple other responsabilities. I find it a bit unfair to complain that things are below your expectations and occult the fact that most Free Software projects are understaffed, be it for code or documentation.
GNOME is not a company, people work on what they like, and a few paid ones work on what they are paid for. You don't like the way Gjs is maintained, and that's fine. Yes, things can always be improved. But that has little to do with the fact that that website is the current official documentation.
So do what you want, you're the maintainer of your own project. I don't use Argos. I don't use Gjs either. I don't even do javascript. But I care about accurate documentation and making it easy for users to find what they're looking for instead of losing time. That's why I thought having a direct link to what has been the official documentation (even if both of us don't like it) for over a year would be valuable.
I honestly don't see how I'm being "unfair". I'm not attacking anyone, nor am I demanding anything. It would be futile to do so. The GNOME project is well known for having a rocky relationship with third-party developers, and anyone who still expects this to ever change is probably fooling themselves. GNOME is what it is, and I have made my peace with that a long time ago.
But that doesn't mean I feel obliged to link to something I consider to be below par just because GNOME says it's "official" in some way. The Argos README is not a GNOME knowledge base. The only documentation that belongs there by right is that for Argos itself. Anything else I evaluate based not just on how helpful it might be, but also how easy it will be for me to maintain. And since I don't have a lot of confidence that it will remain stable, "baznga.org" is out. People looking for a direct link to the current official Gjs docs should just use the GNOME wiki.
Update for anyone who may stumble across this thread:
As of today, the mystery URL recommended above (http://devdocs.baznga.org/) is now domain parked, the documentation is gone and instead the page shows, yes, "Sponsored Listings".
It's been just 8 months since this discussion took place, and already the "new documentation" has been replaced by ads, with no notice and no hint for where to look for the docs now.
Really it is difficult to top the steaming pile of excrements that is the GNOME developer experience. Note that the apparently impossible task that they keep failing at here is hosting a static website visited by just a handful of people at a stable location. My local bowling club has been doing that since the 90s with near-zero tech expertise and a shoestring budget.
I am at least trying to hold on to the belief that this is all just a series of accidents and mistakes, but it is becoming ever harder to do so. Any sufficiently advanced incompetence is indistinguishable from malice.
As I understand it, volunteers help at some point in time, them sometimes go AWOL (which seems to be what happened here).
Some follow-up on https://gitlab.gnome.org/GNOME/gjs/issues/250
Site is now up on https://gjs-docs.gnome.org/ . Hopefully this will avoid past issues.