I disagree that it causes massive confusion.  It doesn't seem like a big
  deal either way, and I think a competant user could deal with either layout.

An important point is that it is reasonable for a user to want to look
at documentation for some package, and then cope with the format that
it happens to be in.  This argues pretty strongly for
share/doc/package.

There is also a consistency problem; html is currently a special case,
rather than having txt/html/pdf subdirectories, there is html and
packages.

I note that info is already a special case, but that makes sense only
because of how info readers work.  Web servers can serve all sorts of
documentation formats - certainly txt/pdf/html.

-- 
        Greg Troxel <gdt@ir.bbn.com>