On Sun, Aug 15, 2010 at 3:30 PM, P Kishor
<punk.kish@gmail.com> wrote:
[...]
did anyone actually do that deployment before writing the docs?
Because, as the docs are, and given the current version of Dancer,
that deployment would simply not work.
Most likely yes. However, Dancer is pretty volatile and even now had another serious overhaul. These are all blessed changes that mostly stem from user requests, listening to user feedback and taking that feedback and changing Dancer appropriately (even if it means major changes) to make users have something they enjoy working with.
What probably happened is that the docs weren't updated with changes - which is unfortunate and it's very good that the Dancer community has people like you who can raise a flag and say "uh.. whoops! missed something!"
I am commenting about documentation. If I say in my documentation that
something will do "b" when "a", I have basis to say that. Now, what
happens with bad documentation is worse than there being no
documentation. Most of the time we developers accuse users of not
reading the documentation, since most users don't rtfm. However, in
this case, the user is diligently reading the docs, and following the
instructions to the t. Yet, the stuff is not working. Everyone is
bewildered. After a while, the user is either going to start sounding
like (and believing that) s/he is wanting others to jump to his
bidding, or the user is going to get frustrated and say, to hell with
this, life is too short to waste on something that doesn't work as
documented.
I don't think it has to be this extreme. If a user tells me "listen, I went to the docs and read that I should do A and then B will happen, but when I ran A, C happened instead." This is a clear sign for me that I probably have a bug - either in the software code or the software documentation.
I really hope no one got the feeling of "RTFM or die" here. We try to answer users that haven't read the docs yet, those that might have read it incorrectly and those that read it correctly but found inconsistencies in it.
We aren't always able to answer. I know personally I don't have experience with a lot of the configuration questions people have so I can't answer them, but if we ever gave you (or anyone, for that matter) the impression of "we don't care about what you do unless you read the docs, and if you still have a problem - it's you!" it's a shame and I apologize in that case.
> You're basically disrespecting the effort people have done to create these
> docs because one documented feature did not work for you. This means the doc
> might need to be fixed (perhaps a line change) or some of the code has to be
> fixed. This happens in projects.
Never happened in any project that I have worked with. I can fully
expect bugs in the code. But, I can't expect bugs in the instructions
on the box. If the box says "Do this and this will happen" then I
expect that someone has actually done that. That somewhere in this
world, there is a configuration under which that documentation is
true. If that is the case, then I can go back to confirming what my
configuration is, and then I can say that look, under such and such
versions, the documentation doesn't hold true.
Sure you can expect bugs in the instructions. I gave an example of a program people now use to *compile perl itself* and you can find quite a few of documentation bugs in Perl docs, in Ruby or Python - not just small frameworks like Dancer.
You will most likely find discrepancies in any project that is volatile (and many that aren't). People change things and forget to update the docs. It's not okay - I agree on that - but it happens.
Most communities are blessed with users that sprout up and say "dude, the docs here are incorrect!" - and I'm not being cynical with "blessed" here.
However, it seems that the particular documentation bug is based on
conjecture. I mean, how can http://myapp/dispatch.cgi work if, in the
filespace (term used by Apache), I have myapp/public/dispatch.cgi?
There was quite a lot of work to get dispatch.cgi out the door. Probably got missed there. A shame and it should be fixed.
You misunderstand me, and to the extent that I created that
misunderstanding, I apologize. But, look, all my carping will
hopefully result in better documentation that is more in sync with
reality, and hopefully make Dancer actually say what Dancer does. That
would be a good thing, no?
It is a great thing.
I have probably written the most number of emails on this list. I have
"bugged" folks on IRC. I have simply not gotten to the bottom of my
problem with Dancer now for weeks. It has come to the point that I
feel embarrassed asking any question about Dancer now. I always think
twice -- am I making a pain of myself? Are folks ignoring me? Am I the
only one experiencing this/these problem(s)?
Never feel bad about asking questions, especially in a community. However, consider the community cannot always answer you. This, unfortunately, can include at times core members or core developers as well. We're not all immune to ignorance in some fields. There's a lot of questions you ask (mainly on setups) that I have no idea how to answer. It happens. Same goes for people who are also extremely busy - happens as well.
Brace yourself with patience (seems like you already done that :) and keep trying. Worst case, don't be afraid to hit new grounds, add fixes and examples to the documentation and show others that will ask in the future how it is (or should be) done.
Either way, the situation is bad -- the developers and think a member
of the community is discourteous and disrespectful, or a member of the
community thinks the developers are ignoring him. Either way, that
open source project doesn't have a very viable future.
Agreed. It should change. I gave up my impression, I hope you could do the same.
The fact is, I want this project to succeed. It is a wonderful change
from the usual, confusing swill out there in the Perl web world. But,
it is patchy. It needs to be fixed.
We're short of fixers. Care to join in? :)
> This is open source, not a company. We don't get money (at all!) and
> therefor no one _really_ has to listen to what people say. We do because we
> care. Telling us that "the docs don't work at all" and that it is not
> necessarily better than "not having any docs at all" will probably land you
> in a position of not being often listened to - even if you are reporting an
> actual bug.
>
> Please, be courteous and respectful. If you find a bug, help us by reporting
> and try *not* to include any bad-mouthing of people's hard work. Trust me,
> you'll get more attention and the stuff you care about will get fixed much
> sooner.
[...] You have spent
more words correcting my possibly wrong attitude than correcting my
possible coding mistakes.
True, and I would do it again if and when I feel people are being disrespectful. This - to me - is more important than having correct code, because if you have people who are demotivated, their code will usually suck. People who have crappy code but are motivated will be able to use that motivation to fix that code.
Same goes for any job and any project I've ever worked on.
That is not to say Dancer has crappy code. In this context it just means motivated people will rush to fix docs, while demotivated people will leave it lingering about.
I have deep appreciation for the developers behind Dancer. I want this
to succeed, to become rock solid, super fast, and dead easy to create
and deploy with. That is why I am sticking to it. If my reports and
questions lead to better docs and better code, that would be good for
everyone.
Agreed, but I would still ask you to do it in a certain way. Like I said, demotivation in the end leads to a dead end.