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

[Mattias Stahre]

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
mattias.stahre@...


---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Henri Bergius]

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

Midgard CMS
www.midgard-project.org




---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Mattias Stahre]

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
> mattias.stahre@...
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: user-unsubscribe@...
> For additional commands, e-mail: user-help@...
>

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[sonic-3]

Am Mittwoch, 7. Dezember 2005 16:59 schrieb Mattias Stahre:

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

Another thing that comes to mind is Midgard terminology, which can be
extremely confusing for new users. For example, it took me quite some time to
figure out that MgdSchema and MidCOM Datamanager Schemas are two separate
concepts. On the list, they are both called schemas for convenience and the
docs on the website are not particularily helpful either. From what I
gathered, MgdSchema was the inspiration for Datamanager Schemas, but this is
not really an excuse for using the same name for an XML-based file that
serves one purpose and a PHP array in the DB which serves a different purpose
in a different part of the framework.
For Midcom Components, it's even worse. From a package maintainer's point of
view, the current naming convention may make sense, but how on earth is on
supposed to know (in the absence of any documentation) that pl.olga.vv
contains methods for displaying view counts and enable voting in other
components (correct me if I'm mistaken)? Wouldn't
midcom.library.votesandviews or something similar be a bit more useful?

Bye,

Andreas

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

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[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
> > mattias.stahre@...
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: user-unsubscribe@...
> > For additional commands, e-mail: user-help@...
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: user-unsubscribe@...
> For additional commands, e-mail: user-help@...
>

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[sonic-3]

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
>>> mattias.stahre@...
>>>
>>>
>>> --------------------------------------------------------------------
>>> -
>>> To unsubscribe, e-mail: user-unsubscribe@...
>>> For additional commands, e-mail: user-help@...
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: user-unsubscribe@...
>> For additional commands, e-mail: user-help@...
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: user-unsubscribe@...
> For additional commands, e-mail: user-help@...
>

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



---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Henri Bergius]

On Dec 11, 2005, at 20:26, Sonic wrote:
> Hi!

Greetings!

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

This was mainly due to MidCOM search tool pointing the links to https  
instead of http. This was fixed
last week.

If you find any other pieces of docs that are not working, please let  
me know.

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

Yep. "midcom" would be a much more sensible default module to end up.  
The current PhpDoc setup
could use some tuning.

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

BTW, now that we have wiki software running for Midgard's  
documentation area, it would be great to
start merging stuff in from your wiki. What do you think?

Some docs on how the Midgard wiki works:
http://www.midgard-project.org/documentation/how-to-contribute- 
documentation/

> Andreas

/Henr

Henri Bergius
Consultant Partner, Nemein
henri.bergius@...

Midgard CMS
www.midgard-project.org




---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Arttu Manninen]

Mattias Stahre wrote:
> 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?

You wrote the first time about the documentation on Wednesday. It's now
only Sunday, which means that there was two workdays that anyone could
have done anything to your proposal.

I have to ask for more patience, these issues aren't solved overnight.

Your voice hasn't been left without a notice. We will discuss and plan
on how to organize the documentation and take the best advantage of
wiki-styled documentation.


--
Adrenalin

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Henri Bergius]

Greetings!

On Dec 11, 2005, at 19:52, Mattias Stahre wrote:
> 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?

I finally took a bit of time to reorganize the Wiki front page to be  
more list-like:
http://www.midgard-project.org/documentation/

What do you think? This should bring the important documentation  
areas forward quite a bit better.

Now, looking at the docs, there are three areas where more  
information would severely be needed:

* Building the site structure: There are currently no docs about how  
to build a site structure in Midgard, creating subtopics as  
directories, and mapping components to them. A simple HOWTO would do  
wonders here

* Customizing the style: Now we have two separate guides for making  
layouts, but frankly both suck. Some love from a web designer who  
knows Midgard would be needed here. The current pages about this are  
http://www.midgard-project.org/documentation/getting-started-create- 
style/ and http://www.midgard-project.org/documentation/howto-midcom- 
styles/

* MidCOM component development: This area would be very useful to all  
PHP developers looking at Midgard. It would be great if Arttu could  
complete his guide there, so Torben could then add his wisdom on  
making efficient MidCOM 2.5+ components.

/Bergie

PS. Mattias, I noticed you run a blog. Want to be included on Planet  
Midgard?

Henri Bergius
Consultant Partner, Nemein
henri.bergius@...

Midgard CMS
www.midgard-project.org




---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[sonic-3]

Am 11.12.2005 um 19:38 schrieb Henri Bergius:

> On Dec 11, 2005, at 20:26, Sonic wrote:
>> Hi!
>
> Greetings!
>
>> 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.
>
> This was mainly due to MidCOM search tool pointing the links to  
> https instead of http. This was fixed
> last week.

Yeah, I know (and I reported this error two weeks ago, BTW), but like  
I said, timeouts for example occur randomly (maybe I'm just too  
impatient, but after 30 seconds, I usually give up). As for broken  
links, sure I can report them when I stumble across them, but I think  
some automated test would be far simpler and more reliable. As for  
empty pages, ok, next time I spot one, I'll post it to the list.

>
> If you find any other pieces of docs that are not working, please  
> let me know.
>
>> 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 :-).
>
> Yep. "midcom" would be a much more sensible default module to end  
> up. The current PhpDoc setup
> could use some tuning.
>
>> 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.
>
> BTW, now that we have wiki software running for Midgard's  
> documentation area, it would be great to
> start merging stuff in from your wiki. What do you think?
>

Well, mine is more like a notepad and should certainly be reviewed  
before any inclusion, but I'm not against doing it (It's all freely  
available). I myself can't do any merging as I unfortunately don't  
have my login password to the site any longer (hard disk crash). I  
mailed you off-list twice about it, but so far haven't heard back...


Bye,

Andreas

BTW: I just browsed through the documentation a bit and it seems to  
have improved quite a bit in terms of navigation over the past few  
days, kudos to whoever was working on it!

One suggestion though: Could the menu on the right side be made a bit  
more useful? Only the same three links on all pages doesn't really  
help you navgiating. The old documentation for example had those  
expanding menus which IMHO where quite helpful. It would be kind of  
nice to have something similar here.

> Some docs on how the Midgard wiki works:
> http://www.midgard-project.org/documentation/how-to-contribute- 
> documentation/
>
>> Andreas
>
> /Henr
>
> Henri Bergius
> Consultant Partner, Nemein
> henri.bergius@...
>
> Midgard CMS
> www.midgard-project.org
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: user-unsubscribe@...
> For additional commands, e-mail: user-help@...
>

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



---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Henri Bergius]

On Dec 11, 2005, at 21:36, Sonic wrote:
> Yeah, I know (and I reported this error two weeks ago, BTW), but  
> like I said, timeouts for example occur randomly (maybe I'm just  
> too impatient, but after 30 seconds, I usually give up).

I've seen the same problem. I wonder whether it is the Midgard memory  
corruption bug or MidCOM cache slowness at play here.

We could try running the site in uncached mode to find this out.

> Well, mine is more like a notepad and should certainly be reviewed  
> before any inclusion, but I'm not against doing it (It's all freely  
> available).

Thanks! I'll go through it and try to find stuff to lift :-)

Anyway, would be great to see this kind of community documentation  
work happening in the
official wiki instead.

> I myself can't do any merging as I unfortunately don't have my  
> login password to the site any longer (hard disk crash). I mailed  
> you off-list twice about it, but so far haven't heard back...

Sorry about that, you should have new passwd in your mail now.

> One suggestion though: Could the menu on the right side be made a  
> bit more useful? Only the same three links on all pages doesn't  
> really help you navgiating. The old documentation for example had  
> those expanding menus which IMHO where quite helpful. It would be  
> kind of nice to have something similar here.

The problem is that now we're in a wiki, which inherently doesn't  
have a tree structure. Maybe
something like categorization there could help, but I'll have to  
think about this.

/Bergie

Henri Bergius
Consultant Partner, Nemein
henri.bergius@...

Midgard CMS
www.midgard-project.org




---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Mattias Stahre]

On 12/11/05, Henri Bergius <henri.bergius@...> wrote:

Greetings!

On Dec 11, 2005, at 19:52, Mattias Stahre wrote:
> 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?

I finally took a bit of time to reorganize the Wiki front page to be
more list-like:
http://www.midgard-project.org/documentation/

What do you think? This should bring the important documentation
areas forward quite a bit better.

 

 

The new layout looks alot better, something more that I wanted to have there. Now it's not so messy anymore and you easy get a nice overveiw of the contents in the docs. I will look cearfully, and maybe come with some ideas if I find something that could be changed. But for know it looks great... Many times better than before.

Now, looking at the docs, there are three areas where more
information would severely be needed:

* Building the site structure: There are currently no docs about how
to build a site structure in Midgard, creating subtopics as
directories, and mapping components to them. A simple HOWTO would do
wonders here

 

 

Yes, that would be really helpful. And maybe some docs on the standardstructure looks.

* Customizing the style: Now we have two separate guides for making
layouts, but frankly both suck. Some love from a web designer who
knows Midgard would be needed here. The current pages about this are
http://www.midgard-project.org/documentation/getting-started-create-
style/ and http://www.midgard-project.org/documentation/howto-midcom-
styles/

 

Yes they both suck :)

Lists of what midgard does generate would be nice, took me a while to figure out what midgard does here and there, and frankly I have rewritten for example the navicode to fit better with my style, and have rewritten alot of the other things. Things like that could go to a  advanced howto, but some easy what midcom puts there as standard would be great in a newbie howto. For example the navi was fun before i figured out why the heck the leaves did fuckup. And why midcom admin fucked up so badly within the design. All the elements Ive found again by reading the HTML source for my webpage, a real trial and error. So howtows about creating a simple layout would be good here. 

* MidCOM component development: This area would be very useful to all
PHP developers looking at Midgard. It would be great if Arttu could
complete his guide there, so Torben could then add his wisdom on
making efficient MidCOM 2.5+ components.

 

The midcom developers should also be better on documentation what their modules do. And why they do. Maybe something about the namespacing for modules example "no.odindata.quickform" that is a formmailer dosent say so much really, or the " pl.olga.vv" well when you see the name it can be ANYTHING. or the net.nemin.ping ... webblog pinger? Well it sounds more like it would perform a standard ping to a server... why not a net.nemin.webblogping for example?

 

/Bergie

PS. Mattias, I noticed you run a blog. Want to be included on Planet
Midgard?

 

Sure. There are not much there yet. But I will start to write alot about midgard, and other geekstuff is my plan. As fast I figure out how to make everything into categorys and stuff like that. Well I will look in your blog later, i do blevie you wrote something about it.

 

Bergie, why don't you post all the great thing found in the blog about midgard development to the midgard wiki? =)

Henri Bergius
Consultant Partner, Nemein
henri.bergius@...

Midgard CMS
www.midgard-project.org




---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

--
Mattias "Plux" Stahre

www.plux.se

[Mattias Stahre]

Im sorry,

you are right.

I did got lite overhand... But ive discussed this with one of the developers for about six months now. And he was telling me all the time he would think about it and forward it. But you are right and im sorry.

 

Mattias

 

On 12/11/05, Arttu Manninen <arttu.manninen@...> wrote:

Mattias Stahre wrote:
> 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?

You wrote the first time about the documentation on Wednesday. It's now
only Sunday, which means that there was two workdays that anyone could
have done anything to your proposal.

I have to ask for more patience, these issues aren't solved overnight.

Your voice hasn't been left without a notice. We will discuss and plan
on how to organize the documentation and take the best advantage of
wiki-styled documentation.


--
Adrenalin

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

--
Mattias "Plux" Stahre

[Mattias Stahre]

On Sun, 2005-12-11 at 19:26 +0100, Sonic wrote:
> 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.

Well why not simple add a broken link feature in midgard? Some kind of
small symbol or something at bottom of every page where people can
report links broken?
>
> 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.
>

Yep, been there done that. And I've used google to snap alot of
developer blogs to find info about things. Hm its alot of timeouts on
the midgard-project.org. But I'm sure that will get better in time.

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

Thats, the way I have done to. And well it's a hard way to learn about
modules. Midgard have a pretty big sorucecode base today.

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