Re: [Fink-devel] Fink documentation: Quite a sorry affair :-/

[Max Horn]

Am 30.07.2005 um 21:16 schrieb Alexander Hansen:

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.


Just wanted to give a heads up here -- things are already better now.  
At least the "Upgrade Matrix". Great work Alexander, thanks!


Max



---
SF.Net email is Sponsored by the Better Software Conference & EXPO
September 19-22, 2005 * San Francisco, CA * Development Lifecycle Practices
Agile & Plan-Driven Development * Managing Projects & Teams * Testing & QA
Security * Process Improvement & Measurement * http://www.sqe.com/bsce5sf
___
Fink-devel mailing list
Fink-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/fink-devel

Re: [Fink-devel] Fink documentation: Quite a sorry affair :-/

[Alexander Hansen]

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 
 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 (

[Fink-devel] Fink documentation: Quite a sorry affair :-/

[Max Horn]

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.


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.
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/).


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. 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 
 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 ?

Unlike the X11 docs, the UG doesn't know about xorg.
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.



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