I agree MSDN's documentation isn't perfect, but trust me, it is far, far, far better than almost every other API's documentation that I've seen. I can't speak to its quality in the 90s.
Also, your second link says """As of Windows Vista, this function is merely a wrapper for SHGetKnownFolderIDList. The CSIDL value is translated to its associated KNOWNFOLDERID and SHGetKnownFolderIDList is called. New applications should use the known folder system rather than the older CSIDL system, which is supported only for backward compatibility."""
(Fun Fact: I implemented much of the knownfolder and some of the old shell32 PIDL folder stuff in Wine :) )
Also, your second link says """As of Windows Vista, this function is merely a wrapper for SHGetKnownFolderIDList. The CSIDL value is translated to its associated KNOWNFOLDERID and SHGetKnownFolderIDList is called. New applications should use the known folder system rather than the older CSIDL system, which is supported only for backward compatibility."""
(Fun Fact: I implemented much of the knownfolder and some of the old shell32 PIDL folder stuff in Wine :) )