mod_rewrite is complicated. It has a million weird edge cases, and behaves different in every context. I wrote a whole book about it, and am in the process of writing another. (https://mod-rewrite.org/ in case you care.) I suspect that whatever we write about it in the docs will be insufficient for someone, since there are as many use cases as there are websites, and mod_rewrite is just very temperamental.
Your contributions have been appreciated. I am skeptical that we’ll ever get to the point where the mod_rewrite docs are simple for all readers, because it’s a complicated topic that takes a lot of experimentation to master. But any small improvement is good. As to the various suggestions to make contributing more accessible - yes, I have been thinking on these for a while. I’m not keen to have our content in a wiki, because that’s a spam magnet, and that’s indeed why we pulled most of our wiki content already. But having more friendly github-based contribution flows feels doable and a good goal. We used to have a comment system on the docs, but that became unmaintained over time. I, myself, have been away from the docs work for almost 10 years, as my focus has been on other aspects of the foundation. In the past 6 weeks I’ve reduced our documentation bug backlog from 170 down to 2. (It’s back up to 6 now, but 4 of those are yours! I hope to knock them out this weekend.) It’s almost inevitable that it’s a bottomless barrel, but we do what we can. > On May 6, 2026, at 7:59 PM, Philippe Cloutier <[email protected]> wrote: > > Hi Rich, > I sent the following to [email protected] a few days ago, but can't see > it in the archives yet, and I didn't receive any kind of reply. Yet, multiple > much newer emails show. > I don't see that this is tracked. This could correspond to > https://issues.apache.org/jira/browse/INFRA-23353 but this is hard to tell > without some understanding of the problem's nature. > I am sorry to bother you, but did you receive my email? In case you did not, > please Cc the list when replying, I would like to see if your mail displays > and whether that could be specific to my account/provider (I am not sure I > ever wrote to an Apache mailing list before). > > -------- Forwarded Message -------- Subject: Confessions, excuses and > [pretend] recruitment advice from a serial bugger Date: Sun, 3 May 2026 > 20:59:33 -0400 From: Philippe Cloutier <[email protected]> Reply-To: Philippe > Cloutier <[email protected]>, Apache httpd documentation > <[email protected]> To: Apache httpd documentation > <[email protected]> > > Greetings―ahem―everyone―ahem―, > I have been administering various httpd websites for a couple decades. As you > may know, it's quite difficult to configure httpd without documentation > unless you master it, so I consulted documentation many times over the years > and thank you for your involvement. > I have contributed to httpd during that time as I stumbled upon various > issues, but all my contributions have been via issue tracking, which is not > always so efficient. Someone pretty well known to this project suggested I > join this mailing list, which I chose not to do. And reiterated after I filed > more tickets. > httpd and the Apache project in general have been fundamental in my life (as > for many others) and it is an honor to contribute and to receive such an > invitation. I think we can agree that the situation is not ideal: > • The rewriting documentation had/has a lot of issues. > • There have been very few people contributing to httpd documentation. > • Filing 1 ticket per (few) problem(s) is inefficient, both for me and > committers. > • Reviewing changes is complicated without an account/checkout (but see > https://bz.apache.org/bugzilla/show_bug.cgi?id=60377#c12) > I am sorry if filing that many tickets is annoying. But as I explained, most > of the httpd issues I reported so far came from various mandates where I > administered httpd. Changes in my roles and in the landscape mean I am much > less likely to be in charge of major services/applications based on httpd, > and I expect both my interest in and my mastery of httpd to keep declining. I > do not intend to abandon my rewriting crusade until I (and hopefully > everyone) understand reasonably well how it works, but I am less likely to > start new crusades, and I cannot win this one alone. > It is not realistic for me to jump in and do all I can to advance this. In > many cases, I am able to point out incorrect or confusing parts, but I lack > the knowledge to do more than suggesting solutions. I also do not speak > English natively; I could fix a few mistranslations in French, but these do > not abound. I also never worked with the manualpages document type. > I am already subscribed to too many mailing lists, some I should have > unsubscribed from years/months ago, so I cannot afford to subscribe to this > one; please Cc me in case you think this deserves a reply. > Recruitment advice > Of course, making proposals cheaper would help, but it is surely late to move > rewriting documentation to the wiki, even if that was a good idea. > The documentation index already has a clear call: > >> We'd love to have your help to improve the docs. > > What else could be done so that more people with more experience and > resources/interest than I do join, and are motivated to keep contributing? > • Commenting on commits à la GitHub/GitLab would of course help, but > requires a huge effort. > • Possibly reworking the "Report a bug" link? Just labelling "Report an > issue or propose an improvement" might be a start. > • My perception is that the rewriting documentation is particularly > complicated. Perhaps adding a call for direct contribution specifically on > rewriting pages could help recruiting. > Thinking about this further, rewriting is probably one of the topics which > are themselves complicated, but one issue I *suspect* with its > *documentation* which may multiply this is that it was never fully reviewed > by a second person. Somehow conveying that to the reader could entice such a > person to get involved. I can think of 2 options: > • Adding some warning on unreviewed pages > • or just adding a list of authors and reviewers of each page. When > there are no reviewers, this could show display some “Be the first.”-ish > invitation. This option would have the benefit of crediting those involved > (yes, there is already a global page for that, but I only saw it for the > first time yesterday, and it is not complete). > • The previous point got me thinking about credit. It was 2 decades ago > that 4 keystrokes/clicks from Firefox would allow one to see my name, and I > still remember the pride which the young adult I was felt from that. Now, I > fully agree that maintaining credits which gives everyone their due share > manually takes time, and automating is tricky. Something like what displays > at the top of https://cwiki.apache.org/confluence/display/HTTPD/RewriteRule > is a good start, without being too distracting. > Yes, I do realize this is likely to be brushed off as “would have been great > if today's (tomorrow's?🙄) CMSs had been available ~3 decades ago.😒 > > Sorry for not being more helpful, and thank you for your involvement > -- > 🅭🄍: https://www.philippecloutier.com/Common+infrastructure+licensing#list > > Philippe Cloutier — Rich Bowen [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
