RDocodile is Dead
As of this morning, RDocodile is no more. The Ruby community showed the barest of interest in the work. Less than seven individuals took watch of the projects on GitHub. I suspect the lack of interest stems primarily from the rise of RDoc’s main competitor, YARD. I had hoped RDocodile would give some invigoration to RDoc, but the maintainer of RDoc itself gave cold reception to the whole endeavor. So I have decided to end development completely. It might seem rather unfortunate, such a large amount of good work going up in smoke, but I’m not bothered by it. Failures compose the soils of success. Instead of looking back, I look forward. And I see even better documentation pastures on the horizon.
Comments
Thank you for your work, it mattered anyway (I don’t go with modern definition of success). No work is ever in vain. Best wishes for you future projects.
Trans, maybe you shouldn’t default to externalizing the blame. Maybe the lack of interest was warranted because the project was written in a vacuum. Every time we code-review your code it is obvious to us that you aren’t writing for clarity or maintainability and yet, here you are complaining that nobody wants to take over your work. It’s no wonder: metaprogramming as much as possible, a lack of testing, dead code sitting around, and copied-in retired code from rdoc (that was removed from rdoc for a reason).
Drbrain evaluated your code and responded with “There is commented-out code, dead code, and code with TODO questions in rdoc-plus making me think your project is not done and is not in a good place. … There are no tests. There is lots of metaprogramming and odd naming … and there is no documentation of how to write a generator” and I have to agree from what I saw. Do you really think it is someone else’s responsibility to clean up your mess?
Why do you think I’m blaming anyone? I think you missed the point.
I had that conversation with Drbrain from which you quote. You fail to mention my response which essentially said, “yes you are right, there are plenty of things to done internally and I am willing to do them if there is enough interest.” Most of TODO work was internal stuff. For the end-user the projects were working fairly well –I automated generation of example documentation utilizing every one of them, so they were being “end tested”. I would also disagree with the metaprogramming comment. There’s really very little, but that’s bedside the point. Most the things that needed to be done where easy things to do, it just required the time to do them. The end-user would not know any of this. I was gauging interest in the end product. If there is not interest there, why bother to continue with the rest of it? Dbrain also expressed disinterest by focusing solely on internal details and expressing zip about on the overall work, even though I expressly said I would continue work if there were interest. Do you think there was interest? He did not even bother to respond to my last query in the conversation.
But Dbrain’s disinterest isn’t even the most important gauge. Rather it is the interest of potential users. There wasn’t even one single comment to the release announcement on ruby-talk or at rubyflow. If you want to believe that was just because it was me or that the code wasn’t prefect yet, you go right ahead. I think it more likely to expresses something else.
BTW, Christoph. Thanks for the encouraging words. I really appreciate that. We need more of your kind of spirit in this field.
Yes, the point was missed… but not by me. “Maybe the lack of interest was warranted because the project was written in a vacuum.”
Nobody cares about it because there was no need for it in the first place. But that’s entirely lost on a “C.S. Imagineer” with absolutely no real job experience. You actually put that on your résumé. Wow.
When I took over RDoc it was well organized but largely undocumented and untested. How anything fit together was a mystery.
Since then I’ve cleaned it up, added some amount of documentation for every piece of the internals, and replaced some of the internals with clear and easy to understand code with good interfaces (other parts were merely unfamiliar) and added thousands of assertions.
I expect contributions to RDoc to increase the documentation, clarity of code or test coverage. In that spirit I could not accept your work as-is.
Perhaps I can say it clearer this time:
First, your work was presented as a monolithic set of functionality, not as individual patches. Individual patches allow me to evaluate each piece as part of a larger vision and don’t force me to guess what it is supposed to do or why it exists. Individual patches is the standard way of contributing to open source.
Second, while the user only cares about the output, they don’t have to maintain the code that generates it. As a maintainer of RDoc, I care about the code that generates it. When a user wants to fix a bug they’ve found in the output, they become a developer and care about the code that generates it. Zero tests, near zero documentation and few examples lower the quality of RDoc.
Open source software needs to be quality all the way down. Very rarely do people get paid to work on improving it which leaves it up to the contributor to get a good feeling about what they’re doing. For me, having to figure out how an untested and undocumented piece of software works is the surest way to eliminate those good feelings.
Your duty as a contributor to an open source project is to present your changes in a form that is easy to evaluate and incorporate. Your changes need to maintain the visions of the maintainers or be presented in a way that can guide the maintainers to a better vision. Your changes need to adhere to the standards of the maintainers. If you’re unsure about how to correct any of these things you need to be willing to modify your changes to make them acceptable.
The way you presented rdocodile to me was as a large, indigestible library. You made no effort to show me what was good about it, you showed no way to integrate it into RDoc, you left it unfinished and indicated that you were not interested in bringing it up to the quality standards of RDoc.
Your contribution was like taking my iPhone, replacing it with an Andriod phone, then telling me “it’s better, I promise!” without any instruction on why it’s better or even how to use it. While both devices do the same things, I’m much more familiar with what I already know.
I think you guys are having a conversation with yourselves, b/c you sure aren’t conversing with me. How hard is it to comprehend: no interest in end product = not worth improving internal code. You’re still going on about the code not being up to your standards and I never made any claim otherwise. Lots of programs start out rough and improve over time, just as you explained, that’s how RDoc was too. But you have not expressed any interest in the end product, and more importantly no on else has either. So there is no point. What are you all going on about? The project is gone. Dead. Buried. Finis. Over. Done With. Finito!
@zenspider what resume? I never published one. so you’re talking out your ass.
Thomas Sawyer’s LinkedIn Résumé, which I’ve saved off as a PDF since someone likes to throw fits and delete things on the internet.
I remember your initial post about RDocdile. I’m sorry you ceased efforts and felt the need to yank down the project.
Post a comment