It seems like this could be a good idea, still the patch has been waiting on his author for more than two weeks now, so I have marked it as returned with feedback.
In light of feedback, I enlisted the help of an actual technical writer (Roger Harkavy, CCed) and we eventually found the time to take a second pass at this.
