Title The documentation needs to be better structured
Priority feature Status resolved
Superseder Nosy List poeml
Assigned To Keywords docs
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
Maintaining the mirror database
Documentation for Developers
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
Installation => Prerequirements
=> Components => apache
Was hälst du davon?
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
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).
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
install from source
Maintaining the mirror database
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.
All issues mentioned here have been fixed around r8000-r8004.
Date User Action Args
2010-03-14 21:59:53 poeml set status: chatting -> resolved
2010-03-14 21:59:18 poeml set messages: + msg162
2009-12-02 02:31:29 poeml set messages: + msg81
2009-10-26 19:49:13 poeml set messages: + msg41
2009-10-08 11:55:43 poeml create