Documented? [LWN.net]

Documented?

Posted Nov 11, 2009 15:18 UTC (Wed) by drag (subscriber, #31333)
In reply to: Documented? by djao
Parent article: GNOME 3.0 in September 2010

Well if you think about it it just made the description "more correct".

Emacs may or may not be a valid entry depending on whether or not that theme is installed. Also there are other themes names possible. You can have a 'vi' theme, for example. So saying that possible entries are 'Emacs' or 'Default' is actually factually incorrect and misleading.

The real problem in the original post, which is a very long running source of anger on lwn torwards gnome, is just the lack of documentation and support for "gtk key themes"; and very specifically Emacs-style keybindings.

And yes the lack of documentation is very bad. Documentation is what makes software usable.

Shitty software with good documentation is superior to excellent software with shitty documentation.

This is a chronic problem with Linux software.

(Log in to post comments)

Documented?

Posted Nov 11, 2009 17:08 UTC (Wed) by nye (guest, #51576) [Link]

Hmm. I consider git to be one of the better documented open source programs, since documentation is extensive and includes numerous examples, often including discussion of what options are for (one of the things I hate is documentation with entries like "--enable-frobnobulator - sets whether or not you want the frobnobulator enabled". Well thanks *so much* for that helpful tip).

Documented?

Posted Nov 11, 2009 19:51 UTC (Wed) by djao (subscriber, #4263) [Link]

I dispute the characterization that omitting the names of the default and Emacs key themes makes the documentation "more correct". As shipped by the upstream source, the values "default" and "Emacs" are the only possible functional values. You can modify your own private installation to add more key themes, but then again, we're talking about open source software here -- any behavior can be customized. That is no excuse whatsoever to omit mentioning the two originally valid values.

Moreover, even if the possibility of local modification is a serious concern, there are far better ways to handle this in the documentation. For example, add a line such as "Depending on local system modifications, other key themes may also be present."

I feel, however, that you are still missing my main point. I am not angry at poor documentation in and of itself. What upsets me is the actively hostile attitude of the upstream developers towards improving the documentation. This attitude makes it impossible for the community to contribute positively, short of forking the software. It drains away one of the most important advantages of open source in the first place.

Documented?

Posted Nov 11, 2009 20:37 UTC (Wed) by tuna (guest, #44480) [Link]

You are accusing the gnome developers of being actively hostile to documentation patches. Do you have any sources or examples to back this up?

Documented?

Posted Nov 11, 2009 21:47 UTC (Wed) by djao (subscriber, #4263) [Link]

Of course, although this thread is getting quite long already. The example is the same example that started this whole thread. The change to reduce the description of the gtk-key-theme option was certainly either introduced or approved by a GNOME developer, and this action is hostile and actively detrimental to improving the documentation.

Even if the change is technically "correct" as per the grandparent post (which I do not agree that it is), there are many natural ways to improve correctness without reducing specificity. It takes an actively destructive mindset to apply the fix that was actually applied.

Documented?

Posted Nov 12, 2009 2:25 UTC (Thu) by rahulsundaram (subscriber, #21946) [Link]

I think it is better to assume goodwill and send a documentation patch than complain about perceived hostility.

Documented?

Posted Nov 12, 2009 4:04 UTC (Thu) by djao (subscriber, #4263) [Link]

I already raised this issue rhetorically earlier in the thread. What possible patch can anyone send? The necessary code is already in their svn/git repository. Just revert to a previous version.

Documented?

Posted Nov 12, 2009 15:09 UTC (Thu) by rahulsundaram (subscriber, #21946) [Link]

A patch can very well revert a setting and the important part is to initiate a discussion in the GNOME development forums. The key is to assume good will.

Documented?

Posted Nov 12, 2009 16:15 UTC (Thu) by djao (subscriber, #4263) [Link]

It seems a discussion has already been initiated, at least: https://bugzilla.gnome.org/show_bug.cgi?id=558198

As I assumed, there was no movement on the issue. However, if you insist, I will go there and raise the issue more forcefully, in a little while, after I get my work done.