... , but in terms of presenting a human-readable regex, ...

I had 3 attempts at documenting it. The one I presented was the least bad to me, as the programmer that constructed it.

Once you see the pattern, it's pretty clear how it works and how to extend it to other situations. What I attempted to do was make the pattern clear.

But that relates back to a long held belief that the guy that writes the code is the worst possible person to document it. I was fortunate enough to work with the services of a s***-hot technical author (actually 3 over the years, one guy and two women), for a long period. His skill was as much in being able to 'forget' his (self-described, limited) programming skills and so ask questions from the perspective of someone with no knowledge, as it was in his writing. His very capable writing skills, and ability to phrase things clearly and concisely, were just the icing on the cake. His inate ability to tease out the detail that mattered and ignore what I (as programmer, designer or architect) though was important (today, this minute, because I just solved the problem) was far more invaluable.

I highly commend and recommend the idea of adding a competent technical author to any team of more than 5 programmers, if you want your documentation to be produced, on time, on budget and in a usable and useful manner. The salary cost of an English Lit, major with a CS minor and a couple of years of exposure to development environments and technical documentation is approximately the same as a CS grad with one year, post grad experience--but the time they will save you, and the quality it will add to your development processes, are worth several times that.

Pick the right person, with the right mix of 'people skills' and (metaphoric) balls to not take s*** from developers and managers who think that their part of the process is more important than the TAs. And endow them with sufficient authority from the get-go to allow them to 'pull rank' on deadlines, when the nicely, nicely reminders approach fails--and they will be a valuable asset far exceeding their cost.

In a small team that might struggle to find budget for a dedicated TA, you can often find one that will also use their, usually strong organisational and documentary skills, to organise and perform a lot of the day to day housekeeping chores--scheduling, timesheet keeping, minute taking, meeting organisation, checkpoint noting, chasing and documenting; even cardboard programmer(ing?:) when the need arises. In that way, they can allow developers to spend more of their time developing, and less time doing non-programming chores they hate doing and so usually put off until absolutely forced to do them--and then do them badly. Overall, they can be a huge time and money saver. As always with personnel issues, getting the right man or woman for the job is essential.