Going through the documentation for several drives in the last week, I
noticed a pattern. I.e. Someone has made the driver teams use a
PS: Excellent idea! Means consistent style of docs! Good call! Would
be nice if there was more content though!!
So since there is a template in use, I have a request for something to
be added to it.
Require every driver team, as part of the documentation effort, to
create an Appendix or section that details all the Default shipping
rules in the Config XML file. By details I mean to first of all list
them, and translate them into prose (WHAT Is being done by the rule) and
then explain WHY it is being done.
Now I understand that sometimes the WHAT or WHY seems so obvious, but
remember that to some of us learning this stuff from the docs, that is
not the case! And then to some of us, who have grasped the WHAT, and
are trying to imagine the WHY, this would help save us the time by
telling us the WHY.
A client mentioned the AD driver would be a great example. I know
roughly WHAT it is doing in some of the Subscriber Create rules, setting
the DirXML-ADAliasName (Create User objects rule). But what are the
regex's explicitly trying to avoid? I.e. It is sanitizing the value by
removing a bunch of possible specail characters... But what exactly?
And then explaining the WHY may be as simple as saying AD treats this
set of characters as specail and not legal in a sAMAccountname value...
I personally made an effort to do this and submitted it to Cool
Solutions (not yet published at this time, but submitted) for the
Subscriber channel Command Transform password set of rules. Took many
pages (13 or so) to do one rule set. Includes traces and walks through
So I understand how big a task it is. So break it up into small chunks
and start doing it, please! We really need it. I think a Wiki is one
way to start with it, and maybe we will be forced to do it that way, but
I really feel it belongs in the documentation!