mod_rewrite doc status (was: a too long title)

On 5/7/2026 7:44 AM, Rich Bowen wrote:
> 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.)


Wow! I do care, congratulations and thank you very much.


> 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.


Indeed. Thank you

I think your book speaks a lot about mod_rewrite's complexity. I hope 
that the documentation can link to your book.

My knowledge of httpd is quite limited, but I don't see any other httpd 
topic of that complexity. I feel like this may be a particularity of 
mod_rewrite, justifying a focused call for help. This could be phrased 
as a call for help integrating external rewriting resources like those 
in the wiki and the book in httpd.apache.org.


> 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.


I am no fan of GitHub, but wikis can of course attract spam. Qt's wiki 
has an approval mechanism which prevents that, although it's based on 
MediaWiki, which has its problems too.


> […]
>
> 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.)


Wow, that should go in the annals! Congratulations again


> […]
>
>> On May 6, 2026, at 7:59 PM, Philippe Cloutier <[email protected]> wrote:
>>
>> […]
>>
>> -------- 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]
>
>
>
>
-- 
Philippe Cloutier
https://www.philippecloutier.com