on Mon, May 24, 2004 at 09:48:57PM +0100, Randy Orrison (randy@orrison.com) wrote:
> Karsten M. Self wrote:
> > on Mon, May 24, 2004 at 10:09:13AM +0100, Randy Orrison
> > (randy@orrison.com) wrote:
> > > Roberto Sanchez wrote:
> > > > Karsten M. Self wrote:
> > > As with most documentation, free and proprietary, it's easy to
> > > find if you know in advance what you're looking for. Going to
> > > www.microsoft.com and entering "HKEY_LOCAL_MACHINE Policies
> > > LocalProfile" into the search box on the front page returns two
> > > hits, different pages with the same content.
> > In the Free Software world, the answer would be a manpage that documents
> > either the entire file structure, or the relevant subtree of a shared
> > structure. Of course, with GNOME rushing madly into fatal embrace of
> > the Registry, *and* abhorring manpages, all bets are off. But we'll
> > file our bugreports here in Debian land.
> [1]
> > But, say, for an application or suite which owned a particular subkey,
> > I'd expect to see:
> [2]
> > - A full listing of keys.
> > - Values.
> > - Behaviors.
> >
> > Anything less would be a documentation bug.
>
> But you still need to know what you're looking for.
No.
As I just posted in response to your original comment: this is new
documentation for W2K3. The docs simply don't exist for any other
legacy MS Windows product. Despite the fact that the Registry has
existed in at least nascent form since Win95 (well, Win3.11 if you want
*really* nascent forms).
*And* the docs are partial and incomplete, specifically hiding behavior
specific to legacy MS Windows. Under a documentation tree that's
specific to that very same product.
> In this case, using the Microsoft reg key as an example, and assuming
> wonderful Free Software documentation as you describe, you'd still
> need to know that the relevant subkey is owned by "policies" rather
> than "login" or "profile" or "active directory" or whatever, and that
> the setting you're looking for is a local profile setting, even though
> the problem manifests itself as a failure in roaming profiles.
Yes and no.
Yes, you need to know how to use the documentation system.
However:
- GNU/Linux *has* the documentation (well, generally, and under
Debian, by policy).
- It has the documentation on the system (or at least the option to
install it via mandb, etc.).
- The documentation tools, even the Johnny-come-latelies like GNU info
(bleh!), are over 15 years old, with highly consistent interfaces.
A mix of 'man', 'apropos', and sniffing through the info indices
will typically show stuff up.
- There are copious ancilary docs. HOWTOs, FAQs, and the rest. Also
online. And when brought under the umbrella of dwww or similar,
indexed automatically.
There is one area that might be comperable at present: the /proc tree.
There's a mess of stuff under there, and not all of it is thoroughly
documented. It's dynamic which makes this even more problematic.[1]
> Hmmm... Not sure where I'm going with this. I guess I'm just trying to
> defend Microsoft from Roberto's implications that they would
> intentionally leave things undocumented[3],
I've shown that they do. Your response?
> and that free software documentation is better than Microsoft's.
I'll grant that it's difficult to make a straight comparison here. I
_feel_ though I can't _prove_ that FS docs _are_ better.
Microsoft makes intentional and strategic masking of valuable
information (APIs, registry keys, etc.), with copious legal record
indicating same. Strategic partnerships with privileged access to
information being a key carrot/stick.
Free software tends to have issues with generating docs in the first
place, ordering them, or keeping them updated (though last speaks to
rapid development and dynamism of projects). In general, however, there
*is* a f*cking manual you can read on a given topic.
Moreover: side discussions such as this on newsgroups and mailing lists
not only serve as ancillary discussion, but often feed back to the main
core. I can point to multiple instances of same in my own list posts,
several of which are now enshrined in Debian docs.
> As an often frustrated user of both Microsoft and open software, I
> feel qualified to say that all documentation sucks, and Microsoft in
> this particular instance doesn't suck any worse than any other.
Perhaps not worse. Though I'm not going to grant you that, I'm just
holding out the opportunity.
Does it suck in all deliberate malevolant intent? Absolutely. We've
got three major antitrust actions (two in the US, one in the EU) on just
that point.
> [1] This is why I'm moving as much as possible and practical from
> Windows to OSS, because OSS is so much more ... open!
Quite. Read Neil Stephenson's "In the Beginning Was the Command Line".
Very specifically his comments on Debian. And see bug #6518.
> [2] I'm not so confident that I'd say I expected to see it, but I'd
> certainly _like_ to see it. What I'd expect would be to be able to file
> a bug report, and be able to dig through the source to figure it out,
> and submit a contribution that would likely be accepted with thanks.
> (See [1])
I've done that. Once. In dillo. On the contributors list even ;-)
I've submitted several manpage wishlist bugs. One within the past week
on a KDE package.
> [3] Yes, I know -- they have and they do. But not in this case, and not
> about in the registry in general. I've found that most every registry
> key I've been curious about I've been able to find either from google
> (there are many third-party registry documentation sites) or
> microsoft.com. Of course, you need to know what the key is first, to
> find it.
That's a big part of the problem. IMVAO: the documentation should be
integral to a registry, similar to what I've described for /proc below.
Peace.
--------------------
Notes:
1. Thought that in itseelf could offer the seeds of a solution:
imagine a "README" entry in each /proc subdirectory pointing to the
appropriate docs. Rich Morin's "Meta" documentation system has
a grain of this idea as well.
--
Karsten M. Self <kmself@ix.netcom.com> http://kmself.home.netcom.com/
What Part of "Gestalt" don't you understand?
Those who would give up essential Liberty, to purchase a little
temporary Safety, deserve neither Liberty nor Safety.
- Benjamin Franklin, 1755
Attachment:
signature.asc
Description: Digital signature