> So, I hate to say it, but...
>
> These things are open source. The source is open. More than that, Haml
> has a decent test suite, which is always a good place to look when you
> want to know how to use some code.I don't know why you hate to say that.
Because in a way, it's admitting that the documentation isn't sufficient, and
it's also implying that you _should_ dig into the source code, that this would
be a perfectly normal thing to do.
That's workable, but certainly not ideal. I hate to say it because I don't
think people should have to dig into source code to get stuff done -- but it
is nice in that you _can_ do that.
> But the point is, while good docs are a good thing, I think working and
> readable code is at least as important.I would agree with that.
But reading the code fundamentally tells you WHAT the code does. I look to
the documentation to find out WHY?
I don't see how that's a problem in the Haml case.
Let me put it this way: I'm not a Haml developer, never have been, but that
took me almost no time to find, and it does make sense to me why it'd be that
way. Specifically, it makes sense that you'd have a template object that
represents some sort of "compiled" form of a template (or at least parsed
form) so that you can efficiently combine that with a given environment (the
self and locals arguments), rather than re-parsing the template on every
request.
This is far from just a Ruby thing -- in particular, I know that Java's JSP
files actually get compiled to .class files, just like any other Java source.
There was nothing in the Sequel documentation that told me how I could get
it to start identifying UUID codes as "type uuid" instead of pretending
they were strings. But the code was fairly readable, and after following a
few class definitions back up into the code, I eventually found a section
that had a case statement regarding db types and Ruby types. and I figured
out what to add to get it to give me UUIDs. There were still a few parts
where I was scratching my head and going "What does this part do?"
Right -- and that makes sense. Documentation generally covers the public API.
If you're hacking on the source, you get to keep both pieces when it breaks.
It would be nice if there was better documentation as to where to get started,
for people who do want to play with the source, but ultimately, if you're
playing with the source, the goal should either be a fork or a patch, probably
a patch.
It's quite possible that the answer on how to get Haml to interpret stuff
was staring me in the face at some point, and I missed it. I'm afraid that
doesn't change my point at all.
Actually, it does entirely. It changes your point from "I can't believe Ruby
won't let me do this," or "I can't believe Ruby makes it so difficult to do
this," to "I might have missed how to do this." One is a statement about the
tool itself -- the language, the framework, or the community behind it -- and
the other is a statement about your ability to interpret it.
It's still a good point, but it's a much more humble one.
Whether I'm too ignorant to figure out from the source code how to
fricassee, or the source code's so poorly written that most people can't
figure it out, or the docs fail to explain it, or it just can't do that in
the first place, the end result is the same: no fricassee-ing.
However, those are each very different problems with very different solutions.
If it's just you, then I should do what I can to give you the tools you need
to be able to figure it out yourself, should you need to. I've been trying to
do that here.
If it's really that poorly written, that absolutely is a good reason to use
something else.
If the docs don't explain it, and it's something that's supposed to be a
feature, the docs should be fixed. However, if the docs don't explain it
because it was never designed as a feature in the first place, but is just a
sort of accidental result of how it's designed, that suggests either it's fine
the way it is, or it should be added as an official, public-API feature with
quality documentation.
In particular, documenting something generally makes it part of the public
API, which means people will be cross if you change it. (If it was documented
but not public, it wouldn't be ideal for your purposes, anyway.)
In the last case, the feature should be added if it makes sense.
Now, the ideal steps for you in each of these cases is roughly the same: "Is
there a way to fricassee? I don't see it in the documentation, and I can't
figure it out..." or "It looks like I can fricassee this way. Is that likely
to change in the future? If so, can I get an official public API for it?"
I don't know if you tried these. If you did and got no response, that's
certainly a failing of the community, and I apologize.
I kept finding
tutorials that would say "or you can edit the blahblah file to work with
an existing legacy database." However, I couldn't even *get* a blahblah
file to edit from either Rails or Ramaze,
Well, but which file? If it was schema.rb, I don't know that it would've
helped...
Sinatra (or rather, the ORM that came bundled
with Sinatra)
Which is that? I wasn't aware Sinatra came bundled with an ORM. I wasn't aware
that it made sense for there to be -- seems like you'd just use an ORM
directly, without Sinatra knowing or caring about it.
Should there be even
more docs for people trying to use Sequel who've never worked directly
with a SQL database before? It *would* make Sequel even more accessible to
more programmers, but it's probably not worth the effort it would take for
somebody to create that much more documentation.
Well, in that case, the idea would be to go elsewhere to learn SQL.
I certainly don't see a clear
path between a code fragment in a test suite to, I guess, embedding
"Haml::Engine.new(@varWithMyHamlCodeInIt)" inside a Haml template. If you
do, please do NOT tell me. I'm not using Haml, and at this point can't
imagine any benefit I could derive that would pay back the cost of
switching my existing code base over to it.
Sorry, I have to, because it's still a one-liner -- the result of that
'render' call seems like it'd be a string, like any other you might generate,
and Haml doesn't escape strings unless you tell it to. The naive usage would
look like this:
= Haml::Engine.new(@var).render(self)
If I had doubts it'd be a string, I'd test it in IRB.
But this, in the end, is all nit-picky detail.
Maybe, and I apologize if that's all it is. My point for getting into this was
to find out where the gap between my experience of things truly being easy
(even when starting out), and your experience of things being difficult or
impossible.
If it's something I can clear up here, that's helpful. If it's something
that's missing from the community as a whole, that's also good to know, too.
like myself, his background and knowledge base were not the
assumed default, and I believe that this was one of the reasons why he
found the whole process so unexpectedly unproductive.
If that's really all it is, then I hope, if nothing else, I've helped bring
you closer to that.
From where I'm standing, it looks like the pain point was going against the
grain while also being a newbie. That's part of why I've beaten this Haml
horse to death -- the answer to the question of "How do I embed Haml code into
my controller?" is generally "Don't do that. Use partials instead." A ton of
newbie questions reduce to something similar.
Unfortunately, we can't do that with all of your problems. For example, my
kneejerk reaction when I see people ask "How do I tie this to a legacy
schema?" is "Don't do that, migrate to something sane." But that's obviously
wrong.
For what it's worth, as badly as we might need better documentation and
tutorials for working with legacy databases, I found it even more frustrating
in the world of Oracle ADF, where an existing, legacy Oracle database
(complete with DBA) was assumed, and there was no easy, step-by-step guide on
getting from zero to a Hello World app.
···
On Friday, October 15, 2010 06:57:42 pm Dave Howell wrote:
On Oct 14, 2010, at 23:18 , David Masover wrote:
