[mirrorbrain] More documentation

Hi,

thanks to the effort of Lars Vogdt from the openSUSE education project, 
there is now a wiki page with instructions how to set up MirrorBrain on
openSUSE systems:

http://en.opensuse.org/Mirrorbrain

This is a great resource and it surpasses the rather poor instructions
found in the INSTALL file[1]. It also contains helpful examples and
instructions for maintaining the mirror database. 

Some (general, strategic) thoughts about this follow!
I realize the need to have documentation easily accessible and editable.
I think that the docs should be accessible both online (web page) and
offline (installed with the sources / binary packages). I also think
that it is very useful to be able to _edit_ the docs in two ways: via
web browser (as in a wiki), and with an editor together with the source
code (in SVN). Both ways are important to lower barriers and effort in
editing them. It is important that users (and developers) can edit the
docs without learning about specific procedures. Both a simple,
wiki-like online thing would seem useful, as well as a simple svn
checkout of the sources.

I was thinking about ways to make both of this possible and looking at
how other projects do it. I find that restructured text[2] is a very
good "base" format for the docs, as it allows generating HTML (or PDF)
very easily, but still is a very readable and easily edited text format.
Now, the idea is to have restructured text files in the svn, and make
them directly accessible as HTML on the web site. At the same time,
there should be a way to edit the files online via the website. I think
that the Django project[3] does it this way. The project excels with
stunningly good documentation, and I believe that their strategy is
fundemantal in this achievement. They use a framework called Sphinx[4],
which is also used by the Python project and many others to generate
their documentation. 

I packaged Sphinx in the openSUSE buildservice, played with it and it
looks great. 
What would be missing is a way to edit the files via the web. The
MirrorBrain web site is run on a Zope server which already allows
presenting restructured text files as HTML (which I used extensively). I
consider migrating the web site to Django, because I believe that these
kind of things would be easier to do then, and there very likely is good
support in Django for editing the sources in exactly the way that I am
thinking of. And most likely, it is possible to have Django edit the
files living in an svn checkout and submit them to svn after a change
was done.
Anyhow, online editing could be seen as optional, as long as it is easy
to edit the files in svn, and the changes becoming online after
committing.

Suggestions and help welcome!

Peter


[1] https://forgesvn1.novell.com/viewsvn/opensuse/trunk/tools/download-redirector-v2/INSTALL?view=markup
[2] http://docutils.sourceforge.net/rst.html
[3] http://www.djangoproject.com/
[4] http://sphinx.pocoo.org/



_______________________________________________
mirrorbrain mailing list
Archive: http://mirrorbrain.org/archive/mirrorbrain/

Note: To remove yourself from this mailing list, send a mail with the content
 	unsubscribe
to the address mirrorbrain-request_at_mirrorbrain.org