[Openmcl-devel] OSX install difficulties

[Dan Knapp]

> 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