Re: [midgard-documentation] How to make the documentation better?

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: user-unsubscribe-b5ZhpPVuLA+tlBvVaVFjCkB+6BGkLq7r@public.gmane.org
>>> For additional commands, e-mail: [email protected]
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: user-unsubscribe-b5ZhpPVuLA+tlBvVaVFjCkB+6BGkLq7r@public.gmane.org
>> For additional commands, e-mail: [email protected]
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: user-unsubscribe-b5ZhpPVuLA+tlBvVaVFjCkB+6BGkLq7r@public.gmane.org
> For additional commands, e-mail: [email protected]
>

Adding sound to movies would be like putting lipstick on the Venus de  
Milo.
--Mary Pickford, 1925