On 13/11/12 12:16, Matthew Weier O'Phinney wrote:
-- David Muir <[email protected]> wrote
(on Tuesday, 13 November 2012, 09:28 AM +1100):
On 13/11/12 05:28, Matthew Weier O'Phinney wrote:
I don't say this as a critique, but just to clarify what I
understand to be the problem. People are frustrated by the state of
the docs, and feel they are unable to do anything about it because
they need the docs to understand how to use the component. But they
need to understand how to use the component to be able to fix the
docs, and therein lies the frustration.
To be honest, the idea of writing a bug report for documentation
feels weird, but I think that's really the best way for us who don't
know the ins and outs of the components to be able to contribute.
The more constructive the bug report, the better, but even a
"Documentation for Json sucks" (I just picked one at random) is
better than nothing. A lot of times it's really hard to see what
needs improvement when you're too close to the project.
Actually, that's a horrible example. Telling us "it sucks" doesn't give
us any idea of what will improve the documentation in that person's
eyes. As such, my inclination is to simply close those reports as
incomplete.
If you're going to create issues, be as detailed as possible:
* "The available options are not documented."
* "This component does not have any usage examples."
* "How can this component be configured at the application level to
work with the MVC?"
* etc.
These give concrete details for a reviewer to try and fulfill. "It
sucks" does not.
What I meant is that in many cases, it is better than nothing. So far
we've had a bunch of posts saying "The docs suck". "The docs for
component x suck" is a huge step up. Yes, the report would still be
quite unhelpful, but it does give us:
1. Flags specific components in need of improved documentation
2. Opens up dialogue between the reporter and a doc writer to nut out a
specific fix.
... that is, as long as the reporter is willing to engage beyond "it
sucks"...
And I didn't realise you could edit in-place on Github! That's just awesome!
Indeed! I've mentioned it on list before, and in the rtfm.org version of
the docs, there's a popup with details; additionally, even on the main
website, you'll see an "edit" link in the sidebar for each page. This
makes it tremendously easy to submit quick fixes for any given page --
so, please, when you come across stuff you *can* fix, use it!
Thanks for the thread -- sorry if I came across harsh, I just get a bit
tired of hearing folks say the docs suck, but who are unwilling to give
concrete feedback on how to make them better. It's a community project
-- engage it, and you'll likely be rewarded! (Or given a pile of work to
do!)
I understand the sentiment. I get bug reports all the time in my own
work where the report is just "Program doesn't work", or "Website is
broken". They are *very* annoying, and I can see why you wouldn't want
to get more of them. I guess what I was wanting to convey was that even
minimal contribution is better than none.
Cheers,
David
--
List: [email protected]
Info: http://framework.zend.com/archives
Unsubscribe: [email protected]
