Hi Nick, 2018-04-19 10:33 GMT+02:00 Nick Kew <n...@apache.org>:
> > > On 18 Apr 2018, at 20:00, Luca Toscano <toscano.l...@gmail.com> wrote: > > > > Before joining the httpd project as contributor I struggled to find good > technical sources about how the httpd internals work, > > Likewise. That’s kind-of what motivated me to start writing about it. > And I remember reading your book 2/3 times when I wrote my first module at work, so thanks a lot :) But that’s not to say it’s any worse than other software projects I’ve > encountered over the years. > There’s always a learning curve, and a struggle to find relevant docs. > OK, things have improved > a lot since “just google it” became an option, but information still needs > unearthing. > > Are you suggesting httpd is somehow *worse* than other software you’ve > hacked in terms of > developer documentation? In my experience it’s actually a lot better than > most, due primarily to > the high standard of API docs in /include/ and in APR, and of course open > and searchable source. I agree that we have a good code documentation, what we miss in my opinion is a high level (but detailed and with examples) up to date overview of how things stitch together when a request is processed. I can give you a recent example from my experience, namely https://bz.apache.org/bugzilla/show_bug.cgi?id=61860. Eric patiently helped me to track down how the response flows through the output filters (ending up in a error response eventually), that helped me a lot to understand more how things works. And it is of course a super simple example for most of the experienced httpd's devs, but for people like me that are still very n00b (and ramping up!) this knowledge is a real treasure that makes the difference between hours of frustration (ending up nowhere) and the same time spent in coming up with working patches and contribution for the project. http://httpd.apache.org/docs/trunk/developer/API.html is a good example about something that is a "bit" old but still interesting and helpful. The same up to date thing for 2.4 could be really valuable for anybody that joins the project (or thinks to do so). http://httpd.apache.org/docs/trunk/developer/filters.html is great but it misses examples in my opinion. I recently discovered for example the .gbdinit goodies that we ship, they could be a straightforward tool to come up with real data in the docs for a simple debug of a request/response. Ideally the quality bar that I would love to have across our dev docs is this one http://httpd.apache.org/docs/trunk/developer/modguide.html, but in my opinion there is still a a lot of work to do :) > > My point is: blogging is fine, but before even starting that I'd focus > on dumping everybody's knowledge in sections of the docs like > http://httpd.apache.org/docs/trunk/developer. It is boring and less fun > than writing C code for sure, but I bet that a ton of people would enjoy > details about how things work. It will be easier for people to spot "liars" > in the web that focus their marketing strategy only on how httpd is "old" > and not performant too.. > > I’ve called out “liars” once or twice. Or more usually, purveyors of > “cargo-cult” whose idea > of Apache is rooted in how things haven’t been since 1997 or so. But I’m > not sure they’re > really the issue. nginx has risen primarily because it’s a genuine > solution, and secondarily > because it’s had the evangelical community that goes with a challenger > against an > incumbent. Now that it’s risen to be a competitor on more equal terms, > the evangelism > still has momentum. Insofar as we care about market share, we could > respond in kind, > preferably avoiding the wilder fringe. > I think that nginx has risen because it is a great tool, and I like the fact that there are more "competitors" that challenge the status quo. What I don't like is when projects that were born standing on the shoulders of giants focus their marketing on discrediting others to gain popularity. Without clear docs that can allow anybody to verify what is true and what not, the end result is a ton of FUD as we are seeing. I would start with improving our dev docs and spread the word via social media (tweets, medium, etc..). Luca
