From: Chad Perrin <perrin@...>
Date: 2009-02-17T07:37:56+09:00
Subject: Re: Good GUI documentation

--eAbsdosE1cNLO4uF
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Mon, Feb 16, 2009 at 07:21:21PM +0900, David Masover wrote:
> Chad Perrin 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.
>=20
> That is very true, and good documentation is very important.
>=20
> However, I stand by what I said. Unless the documentation is=20
> comprehensive, including a thorough HACKING document for how to start=20
> playing with the internals, there's always the chance with any library=20
> that I might have to dig into it and find out what's going on. The=20
> longer and more extensively I use a library, the more likely this is, no=
=20
> matter how good the docs are.
>=20
> So, while I would like to be able to get that library's equivalent of=20
> "Hello World" working without having to read source, and while I do=20
> appreciate a good README at least, I'd say from there on, the importance=
=20
> of documentation vs clean code drops sharply.

=2E . . 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.


>=20
> As an example: Kernel#autoload is reasonably well documented. It claims=
=20
> to use 'require' under the hood. However, when I click "view source" in=
=20
> the rdoc, I get a pile of C which isn't really understandable, at least=
=20
> to me. It's also not very monkey-patchable.
>=20
> So while the docs were great to get it working:
>=20
> autoload :Foo, 'lib/foo'
>=20
> they were problematic when I wanted something more dynamic -- and=20
> there's really no way to do:
>=20
> autoload :Foo do
>  require "some/#{interpolated}/value"
> end
>=20
> I even tried overriding Kernel#require, the way Rubygems does. And=20
> 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.


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

=2E . . but good documentation could make it easier.

--=20
Chad Perrin [ content licensed OWL: http://owl.apotheon.org ]
left (n.): 1. crazy pinko commie agricultural reformer Marxist
theft-culture collectivist; 2. opposite of "right"

--eAbsdosE1cNLO4uF
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.10 (FreeBSD)

iEYEARECAAYFAkmZ6hUACgkQ9mn/Pj01uKXChwCgqlGg7fxkIsRY68cIxHQ1vNt/
ij4AnjzuobKIsY5o8paSXXZtPTFzng9a
=wqII
-----END PGP SIGNATURE-----

--eAbsdosE1cNLO4uF--