All issues mentioned here have been fixed around r8000-r8004.

I received valuable feedback from a user who installed the software (which worked 
satisfactorily), and then the next steps weren't clear at all:

02:19 < TheUni> poeml: if i may suggest, it would be great to have a "I have mirrorbrain 
installed... now what" faq, or explanation in the guide
02:19 < TheUni> after it was all up and running, and i had added all of the sites to the 
db, i had no idea how to actually USE them.
02:20 < TheUni> it wasn't clear that i had to have a local copy, and even then, that the 
mirrors would intercept that local link.


02:37 < TheUni> and secondly, it would be nice to have the option of disabling that 
fallback. reason being, if we were flooded suddenly with downloads before our mirrors 
sync'd, it would be 
                possible for those downloads to bring the server down. also possible that 
we hit our limits and the host takes the server down, thus it would no longer be able to 
act as the 
                face of the mirrors
02:38 < TheUni> so in that case, it may in fact be better to have broken links for an 
hour or so.


And another related suggestion:
It's not clear from the documentation what needs to be done on a regular basis. as far as 
probing/scanning the mirrors, as well as the geoip data. Maybe a few words on scheduling.




I think the above would be catered for by the following sequence of documentation 
sections:



Introduction
Installation
  Prerequirements
  Platform-specific instructions
    Debian
    openSUSE
    install from source
  Basic setup
What next?
Getting started
Maintaining the mirror database
Configuring Reference
Tuning guide
Special setups
Upgrading
Known problems

In the avove, it should be possible to read the intro, skim the prereqs, then choose the 
platform-specific section. There should be clear guiding in the form of "Now, skip to 
section XY for your operating system". In the end of the os-specific section, there 
should be a direct reference to the place where the documentation picks up again into the 
platform-independent part. Very important.

A current problem is that some configuration steps are scattered between the platform-
dependent installation sections. This should be cleaned up so that the platform-dependent 
sections contain only what's needed to install there (and possibly platform-specific 
configuration), while the general configuration instructions should go to the own 
chapter.

A separate configuration chapter is warranted I think because the configuration is 
generally more work than the installation, and it is generally complex enough be worth 
spending more words on it (which would result in considerable duplication otherwise).

Here's a (German) proposal from Lars:


Da fällt mir noch auf, dass http://mirrorbrain.org/docs/ noch ein wenig
differenzierter gegliedert sein könnte.

Vorschlag zur Umstrukturierung - die Überschriften/Inhalte bleiben
gleich:

Introduction
Installation
Upgrading
Configuring MirrorBrain
Maintaining the mirror database
Tuning guide
Known problems

Documentation for Developers
Release Notes/Change History

Dann bliebe aus meiner Sicht noch, die Schritte in "Installation"
etwas "genauer" zu definieren. So das man z.B. direkt Informationen zu
den einzelnen Komponenten findet. (Das Stichwort "geoip" sollte z.B.
nicht nur zu "Using mod_mirrorbrain without GeoIP" führen.) Dann kann
man evtl. auch in den Sektionen "Installation on ...." nur auf
Besonderheiten eingehen?

Mein Vorschlag:
Installation  => Prerequirements
                   => Components => apache
                                           => postgresl
                                           => asn
                                           => geoip
                                           => ...

Was hälst du davon?

CU,
Lars