Good GUI documentation

Ruby
21

On Sat, Feb 14, 2009 at 05:23:59PM +0900, Tom C. wrote:

7stud – wrote:

The language itself isn’t well documented–or even adequately
documented. The documentation is often non-existent or it’s complete
shite. The powers that be could get good documentation for free if they
wanted. This is all they would have to do:

Umm. Having a bad day, are we?

I’m not sure why, but at least 50% of the 7stud posts I’ve read on this
list seem to be the sort of thing you’d expect from someone whose next
statement will be:

. . . and I’m never using this language again!

I haven’t figured out his/her motivations yet.

22


Chad P. wrote: 
On Sat, Feb 14, 2009 at 08:14:43AM +0900, jonty wrote:
  
Although Shoes isn't drag and drop it is very easy to 
create simple ,
and not so simple, gui apps and
it is rather well documented on-line and via its integral manual, you
don't have to worry about widget creation - you just use them, look at
the examples to see what i mean

Although still work in progress it is fantastically cross platform and

has a good supportive mailing list



I have a question about Shoes, actually . . .

Where can I find a list of dependencies for it?  I seem to recall

reading

that it depended on some other Ruby libraries, but haven’t been able to

find a comprehensive list.

The main packages contain everything Shoes needs, but if compiling from source there is advice on needed libraries in the readme

shoes source
23

On Mon, Feb 16, 2009 at 01:49:39AM +0900, Logan B. wrote:

find a comprehensive list.

Shoes is its own Ruby distribution. That’s how you’re able to
distribute a Shoes app without distributing Ruby.

Well . . . that’s a surprise. Thank you for the information.

24

On Feb 14, 2009, at 12:43 AM, Chad P. wrote:

On Sat, Feb 14, 2009 at 08:14:43AM +0900, jonty wrote:
I have a question about Shoes, actually . . .

Where can I find a list of dependencies for it? I seem to recall
reading
that it depended on some other Ruby libraries, but haven’t been able
to
find a comprehensive list.

Shoes is its own Ruby distribution. That’s how you’re able to
distribute a Shoes app without distributing Ruby.

25

On Sun, Feb 15, 2009 at 10:55:16PM +0900, jonty wrote:

[a bunch of HTML]

Thank you for the information. I’d appreciate it if replies to me did
not come in HTML emails in the future, though.

26

Chad P. wrote:

While I disagree with a lot of what 7stud says, I do believe that good
documentation is rather more important than you make it sound.
Sometimes, I don’t want to have to read the source in order to use the
library – or, in some cases, the application.

That is very true, and good documentation is very important.

However, I stand by what I said. Unless the documentation is
comprehensive, including a thorough HACKING document for how to start
playing with the internals, there’s always the chance with any library
that I might have to dig into it and find out what’s going on. The
longer and more extensively I use a library, the more likely this is, no
matter how good the docs are.

So, while I would like to be able to get that library’s equivalent of
“Hello World” working without having to read source, and while I do
appreciate a good README at least, I’d say from there on, the importance
of documentation vs clean code drops sharply.

As an example: Kernel#autoload is reasonably well documented. It claims
to use ‘require’ under the hood. However, when I click “view source” in
the rdoc, I get a pile of C which isn’t really understandable, at least
to me. It’s also not very monkey-patchable.

So while the docs were great to get it working:

autoload :Foo, ‘lib/foo’

they were problematic when I wanted something more dynamic – and
there’s really no way to do:

autoload :Foo do
require “some/#{interpolated}/value”
end

I even tried overriding Kernel#require, the way Rubygems does. And
autoload doesn’t seem to use that custom require.

Contrast this to Rubinius. While I haven’t tried this, it just took me
maybe five minutes on Github, without looking at any documentation, to
find where autoload is defined, and how it it works, and how to get the
effect I wanted (arbitrary code executed when the autoload is
triggered), probably even with the syntax I wanted – all of which, if
there’s a way to do in MRI, it probably requires intimate knowledge of C
and the MRI/YARV internals.

I think I found a grand total of two comments, each one line, maybe five
words.

Now, granted, the Ruby docs can probably be used for much of Rubinius,
to at least find out what it’s supposed to do. But I should stress
again: MRI has good documentation via rdoc, but I just fell off a cliff
when it came to extending. Rubinius doesn’t have documentation on its
website at the moment (though it is in the source tree), but I didn’t
need the docs to figure it out.

27

On Mon, Feb 16, 2009 at 07:21:21PM +0900, David M. wrote:

playing with the internals, there’s always the chance with any library
that I might have to dig into it and find out what’s going on. The
longer and more extensively I use a library, the more likely this is, no
matter how good the docs are.

So, while I would like to be able to get that library’s equivalent of
“Hello World” working without having to read source, and while I do
appreciate a good README at least, I’d say from there on, the importance
of documentation vs clean code drops sharply.

. . . but you first have to get to that point. “Real” documentation’s
primary value is for when you first encounter the library and need to
get
up to speed. A lack of good documentation at that point might just
encourage you to use a different library, after abortive attempts to
figure things out quickly. It has had that effect on me at times, at
least.

Anyway, I don’t see why a library’s API can’t be fully documented. If
its API is fully documented, any behavior that requires one to read
the
source is basically a bug.

they were problematic when I wanted something more dynamic – and
there’s really no way to do:

autoload :Foo do
require “some/#{interpolated}/value”
end

I even tried overriding Kernel#require, the way Rubygems does. And
autoload doesn’t seem to use that custom require.

That’s not a case of using a library; it’s a case of abusing a
library.
That’s not to say it’s “bad”, necessarily. Sometimes, abusing a library
is the right answer. This is just kind of outside the range of what I
was talking about. You’re referring to what amounts to making changes
to the library, and of course you have to read the source if you’re
going to change it.

I was just talking about using the bloody things.

Now, granted, the Ruby docs can probably be used for much of Rubinius,
to at least find out what it’s supposed to do. But I should stress
again: MRI has good documentation via rdoc, but I just fell off a cliff
when it came to extending. Rubinius doesn’t have documentation on its
website at the moment (though it is in the source tree), but I didn’t
need the docs to figure it out.

. . . but good documentation could make it easier.