On 04/06/2010 09:52 AM, Rich Bowen wrote: > > On Apr 6, 2010, at 12:05 PM, Rasmus Lerdorf wrote: > >> It's custom code for our docs, but it probably wouldn't be too hard to >> bolt onto another system. Start here: > > Thanks so much for the thorough summary. This is very helpful. > > As to whether we'll actually do this, I don't know. Expect a certain > amount of resistance. User commentary without a concerted effort to > incorporate that commentary back into the docs is, as Robert says, a > recipe for unlimited quantities of crap attached to the docs. On the > other hand, the Apache HTTPD docs are *WAY* smaller than the PHP docs. > We have (last time I counted) a total of 229 doc files. I count 10809 > .xml files in the doc-en svn repo. So incorporating that feedback is a > much smaller job than it is with the PHP docs. > > Mostly I'm feeling that our docs don't answer the questions that folks > are actually asking, and I am looking around for ways to rectify that. > This is one idea that was floated.
Yes, documentation is tricky. People, especially PHP users, come from so many different experience backgrounds that it is almost impossible to write one set of docs that speaks to everyone. There are things in the user comments that I have seen people pick up on that I would have thought was completely obvious and unnecessary to document, but turn out to be extremely helpful to a few. I think the bulk of our user comments are never going to get folded back into the main docs as they tend to repeat the main docs in a slightly different way, but are valuable in their own right simply because they explain the same thing from a different perspective. -Rasmus
