-- David Muir <davidkm...@gmail.com> wrote (on Tuesday, 13 November 2012, 09:28 AM +1100): > On 13/11/12 05:28, Matthew Weier O'Phinney wrote: > >-- Marc Tempelmeier <m.tempelme...@bqs-institut.de> wrote > >(on Monday, 12 November 2012, 08:51 AM +0100): > >>What I see in the channels is that there is some kind of rest period. > >>There are a few who make the modules site, but in the whole it seems > >>really quiet. Ok, the last weeks were hard, but there has to be some > >>kind of focus to the documentation in the near future. > >There was a call to arms for documentation around the time of the stable > >release at the beginning of September. A lot of effort was spent of the > >next 4-6 weeks by a variety of contributors to expand the docs and make > >them better. The docs we have now are already light years better than > >they were at the time of the stable release. > > > >There's always room for improvement. > > > >If you feel there should be improvement, and have _concrete_, _direct_ > >ideas on how to do that, please share them, and please assist. This is a > >community project; grousing about the state of the documentation is > >energy that could be better spent helping make them better. > > > > > 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. > 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!) -- Matthew Weier O'Phinney Project Lead | matt...@zend.com Zend Framework | http://framework.zend.com/ PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc -- List: fw-general@lists.zend.com Info: http://framework.zend.com/archives Unsubscribe: fw-general-unsubscr...@lists.zend.com
