[Dancer-users] dancer bug

[sawyer x]

On Sun, Aug 15, 2010 at 3:30 PM, P Kishor <punk.kish at 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.

--

Now that we're done with this, I want to thank you for opening the proper
tickets in the correct place. That will definitely help track issues.

Would you like to help correct the docs? This is where user experience is
the most important!

Sawyer.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.backup-manager.org/pipermail/dancer-users/attachments/20100816/41f8b872/attachment.htm>