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]
