[Openmcl-devel] OSX install difficulties
dankna at accela.net
Thu Sep 30 18:48:47 EDT 2004
> Yeah, it's important to not clutter the docs with tidbits that help
> people, because that will get in the way of people who know what
> they're doing and are re-reading the docs trying to make sure they are
> correct or have operations out of order...
> Actually in point of fact if the docs are cluttered with command-line
> trivia fewer people will read them at all --- I think the degree to
> which the documentation should say anything about
Hmm, this is an interesting difference in viewpoint. I see what you
mean and I agree that
too much information can be a problem. I like the idea of a
troubleshooting section, but I
see it as orthogonal to the problem of writing sufficiently-detailed
directions. When a mistake
is frequent, the directions should just mention it in advance rather
than letting the user make
it and only then providing advice.
In the clear light of morning, I do kinda think the whole paragraph
about Stuffit that I put in last
night is unnecessarily verbose, especially when it's tagged
"important". And yes, details of
configuring shells and other external programs are not our problem to
deal with, clearly.
I see potential problems, but I think I'm going to try the
troubleshooting section and see
how it goes. I'm not thinking of anything big, but I won't have a
chance to work on it tonight;
ought to be ready tomorrow.
-- Dan Knapp
More information about the Openmcl-devel