Hi!
One idea might be to remove all the broken links. There are more than
enough free link checkers available (the one at w3.org doesn't work
with the midgard site, though), so all it takes is a test rn and some
fixing.
As to your question: I found that the only relatively reliable way to
work with Midgard's documentation is to use Google Search to navigate
and google cache to display the actual pages. After weeks of getting
random login prompts, timeouts, empty pages and 404 errors, I had to
resort to this method and found that while it is not really
comfortable, it is at least reliable and turns up more information
than navigating the site directly.
What is partly usable is http://www.midgard-project.org/api-docs/
midcom/stable/ (although I have to laugh every time I read "welcome
to undocumented!" on the start page. This should be the motto for all
Midgard dcumentation :-). Personally, I'd recommend keeping a copy
of the source around for grepping, too. this way, I found many
interesting things which are nowhere in the docs.
Another way to get to know the system is to print out the variables
available (like the contents of get_custom_context_data or whatever
it is called). Unfortunately, var_dump fails more often than not, so
you might have to come up with some code of your own (I've written
something for my own purposes, but it is too buggy to be generally
usable).
So all in all, learning Midgard has, ATM at least, more to do with
reverse engineering than with reading docs. Maybe one should simply
provide a howto to that and some simple tools (like a variable
Browser for the numerous arrays and objects like $_MIDCOM).
FWIW, I've summed up some of my findings here: http://
midgardwiki.contentcontrol-berlin.de I'm fairly sure that half of it
is completely wrong or at least inaccurate, but hey, maybe it can
provide a few clues.
Bye,
Andreas
Am 11.12.2005 um 18:52 schrieb Mattias Stahre:
Is there NO one that have ideas about how to improve the
documentation?
I belive it must be more people than me that uses documentation, and
know what they think about it, and maybe have some idea on how to be
improving it?
On Wed, 2005-12-07 at 18:05 +0100, Mattias Stahre wrote:
Hi again,
was out on google for a bit and found some projects aiming on
standards
for documentationwriting, maybe could be worth looking at?
http://www.oasis-open.org/docbook/
http://developer.gnome.org/documents/style-guide/
maybe can give some inspiration and ideas for how to format and
manage
the midgard documentation?
On Wed, 2005-12-07 at 16:59 +0100, Mattias Stahre wrote:
Hi,
I feel that something that need to get started working with is the
midgard documentation project. Alot of things that are linked in the
docs will give you a blank page, with a title or a 404 page.
(example
http://www.midgard-project.org/documentation/midcom) Well thats
no good.
This would be the primary thing to fix.
Then think about how to present the docs, the links are often
embedded
within alot of text, making it hard to get a good view of what
really
are documented. A way to structure it maybe could be something like
http://typo3.org/documentation/document-library/Matrix/ or maybe
something like http://www.gentoo.org/doc/en/handbook/handbook-
x86.xml
there you instantly get a pretty good picture of the
documentation, and
what there is documented.
I'm in a learning phase of midgard and well frankly I've never
used the
docs, I've spended several hours of googling to find the developer
blogs, and alot of time reading the source code of midgard/midcom to
learn how things work. That's not a good way to do it.
Also I would like documentation to be available as PDF and such, its
much more easy to print and manage than a website.
I've talked to alot of people about midgard, today they see
midgard as a
developer playground due that the docs are pretty bad. I'm right
now in
a project where it was deiced to use typo3 instead of midgard just
because midgard lacks a proper documentation.
What I would like to see from the documentation project is:
* Better overview of the documentation (more organized)
* A complete documentation covering all the modules and
everything in
the midgard sphere.
* Complete reference of the modules (for example how the default
schema
and config looks like for it)
* Tutorials, how to work with aegir/customizing modules. (one way to
write a tutorial is perhaps to find a complete site project that
would
need customization of modules to work and describe what to do and
where,
like many "newbie" coding books use).
* A standard that goes complete all over the docs, how to write,
how to
format etc.
Greetings
Mattias "Plux" Stahre
[EMAIL PROTECTED]
--------------------------------------------------------------------
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
Adding sound to movies would be like putting lipstick on the Venus de
Milo.
--Mary Pickford, 1925
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
