Hey gang, I'm attaching a letter that addresses my general observations and opinions about Midgard's documentation. I meant to send this to the group with mine and Dana's FINAL rewrite of SiteGroups but that document is complicated and we're working on it. We'll be posting SiteGroups in the next day or two. In regards to the Midgard Style, I'll do more research on this and hope others will contribute their ideas. Ron Parker Mi-Recordz www.mi-recordz.com [EMAIL PROTECTED]
Hey gang, In an attempt to help focus the groups effort to produce a publishable Midgard manual, I've written the following letter which includes my observation on the outline of the Midgard manual and proposals for a Midgard style, licensing of documentation, identification of individual roles, and working spirit for the group. I've also included an entirely inadeqaute inventory of the documentation team. PUBLISHING CONCERNS I've been reading "So You Want to Write a Book?" which is O'Reilly's guide for establishing an agreement between them and prospective authors. Midgard is a freely available OSS application server which is one type of project that O'Reilly is interested in. To my knowledge there aren't any other documentation efforts for Midgard. So, from a publishers perspective, we haven't got any competition. However, Midgard lacks the necessary number of users to purchase the manual and return the publisher's investment. It seems obvious that Midgard will eventually appeal to a large audience because of its enhancement of the Apache, PHP and MySQL networking environment. By providing quality documentation, we'll help Midgard attract enough users to capture the interest of a publisher. I suspect O'Reilly will take some interest in helping us whether we're ready for a publishing contract or not and as our user community grows, we'll be poised and waiting with our manual. I'm ignorant about the licensing for the current documentation but it seems obvious that our group's documentation should be owned by Midgard Ry and in the event of publication all revenues should belong to Midgard Ry. If the documentation isn't clearly licensed, an effort to license the documentation should be made. I think licensing falls under the care of Henry and the Midgard Ry board. O'Reilly requests that an example of our work be submitted as part of the appeal for a publishing contract. Dana Bailey, my business partner, and I will do our best to complete the SiteGroup document which we've all been working on for the last couple weeks. The effort that produced SiteGroups, I believe is an excellent example of how our group can produce an application and the supporting documentation. Emile wrote the code and then provided the first written draft. Of course several of us began making contributions at that point. I suspect the SiteGroups document will be the best example of our documentation when it's finished. Presenting the manual as an example of our work is not typical--normally one author appeals to a publisher on the merits of the quality of their product and their ability to meet a schedule. I believe the documentation effort should mirror the core developers example, we can work as group where the spirit of producing a superior product and enjoying each other's qualities is the precedence. An index for the Midgard Manual already exists it is the outline for the manual. I suspect the outline will change as Midgard matures and includes new features. Publishers, including O'Reilly, accept sgml and DocBook markup as a publishable format. Our manual is in the DocBook format, although there are code errors which have been revealed by sgmltools, thank you Emile. GROUP SPIRIT In my mind, the success of Midgard hinges upon our appeal to Webmasters rather than publishers. It's important to maintain focus on what we enjoy, rather than saddle ourselves with the frustrations of seeking publication. If a user says, thank you for making my job easier, we are a success. The effort to document SiteGroups became frustrating for me when I thought we were close to a finished product and Emile presented a major rewrite. After turning my dog into a lamp shade, I realized that I was wrong. Emile knows exactly what content needs to be in SiteGroups and my job as a writer is to make sure that the information is comprehensive. I'm editing Emile's latest version now and should have it finished in the next day or two. My motivation for being involved in Midgard is from an end users perspective. I need a tool that will help me publish a killer product. I became interested in the publishing industry in 1993 and enrolled in a university of liberal arts where I was able to study Associated Press News Reporting. I want to give something back to the Midgard project and writting is one of the contributions I can make. While I feel somewhat unsure of asserting myself in an effort to document Midgard, I figure what the hell--we need a manual and I'm just going to start kicking and let the dust settle where it does. DOCUMENTATION TEAM, ROLES Ron, I'll continue to help rewrite documentation that is provided by the developers and attempt to do something with the Building A Site tutorial which I've started. I'd like the tutorial to be reviewed by the group so a vote on it's usefullness can take place. I know that parts of the tutorial are useful but the direction of the overall manual needs to be considered and identified. Also, I'd like to continue developing the Midgard Style Guide. I'll use O'Reilly's style guide as an influence. Emile, I think we need you to code blobserving and then begin documenting it. I'll begin editing your work and then keep posting the results to the group until it's ready for a copy editer. Unless someone else wants to work at rewritting it. Cat, I really appreciated the improvements that you made on sitegroup03.txt, I think that was the version, and believe all the Midgard documentation is desperately in need of your attention. The entire website needs copy editing. Ami Ganguli is working on documenting the API calls. Armand A. Verstappen and Sean D Ackley are combining their efforts to maintain the documentation. There are in fact numerous DocBook errors in the existing CVS. Ken Polley has expressed an interest in helping with the Content Management section of the Building A Site tutorial and has already provided documentation for that topic within the manual. MIDGARD DOCUMENTATION STYLE This is my first draft for identifying a Midgard Style. I've recently discovered O'Reilly's style guide and will study it and marry the two together. For the time being I'm hopeing this will help all of us realize that a style guide for the Midgard manual will help ease our challange. Order, Presentation Of Information I think our goal should be to create a manual that's predictable. When the reader studies a feature they learn the Midgard style for presenting data. When a manual has many features and each one is presented with the same order of information (style), the reader becomes capable of predicting where and how to find answers. The final version of the SiteGroup document will demonstrate the style that I'm proposing. It conforms to the following guidelines: *introduction; parenthetical and supplies the reader an overall perspective. *configuration; parenthetical explaination which leads to step-by-step directions which may take the form of a bullet list. *usage; parenthetical explaination also includes step-by-step directions which may use bulleted list of instructions. Copy Editing Each sentence should be an attempt to introduce one thought. The use of paranthesis as an introduction to secondary thoughts should be avoided. Redundancy must to eliminated. Every extra word or repeated thought needs to be eliminated or rewritten. Section Headlines Every attempt should be made to write subject, verb, object constructions for chapter and section headlines. Inverted pyramid The first paragraph of every chapter and section must be written to encompass all the concepts that are being introduced to the section. Subsequent paragraphs provide detailed explanations of the concepts that were introduced in the in the opening paragraph.
-- This is The Midgard Project's mailing list. For more information, please visit the project's web site at http://www.midgard-project.org To unsubscribe the list, send an empty email message to address [EMAIL PROTECTED]
