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

On Dec 7, 2005, at 17:59, Mattias Stahre wrote:
> Hi,

Greetings!

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

First thing fixed in this regard was the search engine results  
pointing at HTTPS (which requires auth). Now searches should again be  
more useful.

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

Yep. Based on our IRC conversation, this seems to be the best  
organized documentation area so far:
http://www.midgard-project.org/documentation/installation/

> Also I would like documentation to be available as PDF and such, its
> much more easy to print and manage than a website.

We used to have a PDF generated out of the docs. Maybe I should do  
some work
to revive that again.

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

Yes, the documentation situation is pretty bad in other areas except  
installation
and API docs. Especially regular (end user) usage, and site setup  
would need
some volunteer effort.

If anybody would be interested in contributing to those areas, please  
let me know.
In the meanwhile, I'll try to organize the documentation front page  
better.

> Mattias "Plux" Stahre

/Bergie

Henri Bergius
Consultant Partner, Nemein
henri.bergius-ZpG/[email protected]

Midgard CMS
www.midgard-project.org