The documentation needs to be better structured #9

Closed
poeml opened this Issue Jun 5, 2015 · 0 comments

1 participant

@poeml
Owner
                                                                                         [          ]

Issue migrated (2015-06-05) from old issue tracker http://mirrorbrain.org/issues/issue13

Title    The documentation needs to be better structured
 Priority   feature            Status       resolved
Superseder                    Nosy List     poeml
Assigned To                   Keywords      docs

msg33 (view) Author: poeml Date: 2009-10-08.11:55:42

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

msg41 (view) Author: poeml Date: 2009-10-26.19:49:13

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

msg81 (view) Author: poeml Date: 2009-12-02.02:31:27

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.

msg162 (view) Author: poeml Date: 2010-03-14.21:59:18

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

History
         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

(end of migrated issue)
@poeml poeml closed this Jun 5, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment