Blanket commentary--I'm seemingly the only one working extensively
with the general docs, and lets face it, when I spend 65 hours a week
at work or in transit (and now I'm working on work-related stuff on
the train more often than I have been in the past) it's going to be a
slow process to update everything. I'm sufficiently busy that I
really don't have time to read through all of the docs looking for
inadequacies.
I've made changes as I've noticed things.
On Jul 30, 2005, at 1:31 PM, Max Horn wrote:
Yo folks,
I was tending to many old open bug reports on our tracker for the
past two weeks. During this time, I had to advice people several
times on how to properly upgrade their fink/Fink, X11 and other
things. This lead me to consult our docs. What I saw was somewhat
saddening :-/.
I mean, it's nice that we now have a User Guide translated to 7
languages; but (no offense meant) while I appreciate the localized
docs (great work!) I think it would be more helpful if the
information contained in the english "master" docs was accurate and
up-to-date. The translated versions would benefit from this, too,
of course.
And it would be nice if people could fire off a message with
_individual_ item suggestions (as Max has done) either to me or to
fink-i18n.
Maybe we can find some people who can dedicate themselves to go
over the docs and get them into a more useful state? It would be
nice if I could point people simply to an URL which tells them how
to update / upgrade their system instead of having to explain this
every time again.
Alas, so far I am only complaining w/o being specific, so let me
give you an overview of the problems I have encountered.
* http://fink.sourceforge.net/download/upgrade.php
An important page, but it shows a pattern visible in other spots
of the docs, too: It talks in detail about versions of Fink up to
0.3.0 (which probably concerns less than 1% of our user base these
days, probably far less). The latest Fink it talks about explicitly
is 0.5.0, and it refers to SF.net changes in 2002.
And the prior OS update was in 2003...and if I recall correctly the
10.2-gcc3.3 -> 10.3 update wasn't as painful as 10.3 -> 10.4.
Worst of all, it contains no information on how to upgrade from
10.3 to 10.4; I know that this is a rough process, but it could at
least duplicate the information from the 2005-06-09 news item (see
http://fink.sourceforge.net/news/).
However, I thought it would be kind of pointless to put instructions
for 10.3 -> 10.4-transitional, when I thought that the "real" 10.4
distro was coming out soon, with a completely different set of
instructions. The doc system is time-consuming to work with, which
makes me reluctant to commit anything that I'm going to have to take
away.
My suggestion: scrap all the old shit on that page (or move it to a
second page), and concentrate on 10.3 & 10.4 users here. The table
which maps OS X versions to Fink releases would fit here nicely,
too (copy the data from the front page).
* INSTALL / INSTALL.html / http://fink.sourceforge.net/doc/bundled/
install.php
About the same problems as with the upgrade matrix. In particular,
it lacks an "Upgrading from 0.7.x" chapter: Neither does it tell a
0.7.0 user how to update to 0.7.2, nor how to update to 10.4.
Maybe a generic "Upgrading an existing install" chapter would be
more helpful anyway.
For general issues, yes. For OS upgrades, not so much. Each OS
update has required a completely different strategy for the update
than its predecessor.
Or maybe trim INSTALL a lot, only include the core information,
strip all 0.3.x etc. stuff from it and insert pointers to the
User's Guide.
In my eyes, it'd be better to completely remove the current INSTALL
file than to keep it in its current state, as it causes more
confusion than it helps. Of course I'd prefer a fixed version, but
if nobody is willing to write one, this might still be our best bet...
* User's Guide <http://fink.sourceforge.net/doc/users-guide/
uguide.en.html>
This is still at 10.3, and doesn't list 10.4 among the supported
systems. As such the update instructions are outdated here, too.
Worse, it claims 0.8.0 was for 10.3. Looks like a blind search &
replace took place ?
No, it wasn't. Somebody (not I) had the brilliant idea to put the
latest Fink version as a logical that would be updated dynamically
when the distro was updated--I think this was when we were on 10.1.
We could go with a strategy of having two such logicals, since we've
generally been supporting the last two OS versions.
Unlike the X11 docs, the UG doesn't know about xorg.
Didn't get to it yet.
The important section "Upgrading the Source Distribution" could be
easier to read, too. Maybe remove all the cruft about Fink 0.2.x;
nobody uses that anymore. So "selfupdate" is the way to go. Some
more examples here (of typical user input / output) would be helpful.
Once again, I haven't gotten to this.
That's it -- I haven't delved into the other docs, so I won't
comment on them.
Cheers,
Max
-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Fink-devel mailing list
Fink-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/fink-devel
