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.
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?
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?"
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.
"I couldn't make the Frobulator fricassee."
"Oh, the Frobulator can definitely fricassee."
"I couldn't find any information about it in the documentation."
"Well, it's not in the documentation as such, unless you already know that fricassee is just a special case of fricolating a tri-fold array. But it's easy to find in the source code."
"I haven't been able to figure out how this code works."
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.
I could tell pretty early on that my biggest problem with finding a good ORM was not that there were very few that were *capable* of doing what I wanted, but that very few of the people who'd written the documentation were describing their ORM's capabilities from the point of view that I had: from the database, instead of from the middleware. 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, because all the tutorials and documentation took it for granted that I was interested in making a new web site from scratch, and didn't really care all that much about the details of data storage.
Sinatra (or rather, the ORM that came bundled with Sinatra) had a tool that was supposed to build me a class/object ORM file from my schema, but it couldn't handle UUID primary keys, so it only created about 33% of the material I needed.
I then had to decide if it would be more efficient to just walk through the whole tutorial, learning about scaffolding and migrations, knowing that I would not have any use whatsoever for knowledge related to migrations, until I finally knew enough about the whole system that I would have the background needed to understand the code well enough to be able to figure out how to make it do what I wanted, OR would it be a better use of my time to start over with some other ORM or library or whatever, where I would be able to get started sooner by being able to take better advantage of my existing knowledge? I chose the latter route, although I would not be able to prove to somebody if it was the better choice or not.
The better I get at reading other people's Ruby code, the less I'll need to rely on good documentation.
There is a nebulous point of diminishing returns, where "better" (aka "more) documentation becomes a waste of time; there is a certain amount of knowledge that the user/programmer can be expected to know. For example, the Sequel documentation takes it for granted that I am totally familiar with SQL; most of the docs explain what the code does in terms of the equivalent SQL code. 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.
Certainly my inability to get Haml to work for me does not mean that its documentation sucks, or that it sucks. It just didn't work for me.
It took me about three minutes to find this:
http://github.com/nex3/haml/blob/master/test/haml/template_test.rb
In particular, this line:
Haml::Engine.new(File.read(File.join(TemplateTest::TEMPLATE_PATH,
"_#{name}.haml"))).render(self, locals)
Seems to me that you'd just replace the "File.read" part with the source of
whatever you're trying to render. Note that this will likely be _much_ more
efficient if you can keep the Engine object around, and that's true for any
template system, which is probably why it makes more sense for you to take
whatever you were going to do here and put it in a partial...
Honestly, I have no idea what you just said. 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.
But this, in the end, is all nit-picky detail. My original discussion was all about how the current cacophony of Ruby-based middleware was actually quite cool and powerful, but that the original poster's to make something that is so often described as "really easy" to work at all was not some giant Ruby conspiracy or a massive delusion on our part, but reflected the fact that, 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.
···
On Oct 14, 2010, at 23:18 , David Masover wrote:
And finding a