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 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). > Hm, buggy the word is. I have something like it yes. > 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). > Good point, I do belive it cant be to hard to write for an experinced developer. > 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. > > Good site, it has alot of things iv'e been looking for reagarding the midgar docs I havent found there. Good Work. Hm, maybe we could post things into the midgard-wiki project on midgard-project.org? Or atleast link it from there. > Bye, > > Andreas > Bye, Mattias > > 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] > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
