[wp-docs] Handling Version Differences in Documentation

[Tor Bjornrud]

This started as a wiki "talk" post on the Codex, but I think it's a bit 
long to clutter up the "Codex Guidelines" discussion.

Any thoughts on how we should handle the difference between WordPress 
versions in the docs?  For instance, the directions for "Customization" 
will be very different from one another depending on the version of 
WordPress the user is customizing.

I know this a relatively hairy topic, and the only reason I bring it 
up, is because Mediawiki's documentation suffer[ed|s] from problems 
with anachronisms like rot or documented features that're not in the 
stable release of Mediawiki.

I think that some sort of standard notation is best, akin to the way 
the PHP Manual [http://www.php.net/manual/en/index.php] describes the 
history of a function.  Here an example 
[http://www.php.net/manual/en/function.implode.php].  Notice how it 
outlines the version numbers the function is present in, and has notes 
depending on quirks for the version number?  The downside of this is 
that it doesn't seem to fit well for large blocks of explanation.

I think MediaWiki tried namespacing their corresponding documents to 
different versions, but only ended up unreasonably increasing the 
amount of documentation to maintain.

This all started when I thought about writing up some docs for 
customization, but realized that they would either be obsolete with 
1.3, or that they wouldn't be relevant now (without proper notes) as I 
use a cvs copy of WordPress locally.

Anybody have any bright ideas?