Hi, this thread took many twists and turns, so I'd like to summarise what has been discussed so far and comment on it. I would also like to explain the differences between the documentation that is shipped with the openSUSE distribution and the Wiki. Last but not least I will announce a future documentation project (Lessons for Lizards, LSL), that will hopefully address some of the critics issued in this thread.
For those who know me from the opensuse-wiki list (hello Rajko, jdd and Christian ;-) ): I am not only part of the wiki team - my primary function is being a writer on the SUSE documentation team. Shipped manuals vs. openSUSE wiki --------------------------------- Current state is, that we have two kinds of documentation for the openSUSE distribution: * shipped manuals * openSUSE wiki The approach of the shipped documentation is to guide the user through the installation (Start-Up guide), to give a general overview of the user interface (KDE and GNOME guides), to enable him to configure and run enhanced services (Reference guide, AppArmor). It is designed to help the majority of users, regardless of knowledge, hardware, etc. The documentation is updated with each openSUSE release (approx. every 6-8 months). The shipped manuals are written by the Novell/SUSE documentation team at different sites across the world. They are derived from the "official" product documentation of various Novell/SUSE products. Because product documentation has to follow a product specific structure, company internal styleguides, QA and other internal processes, it can't be open in the usual sense. Consequently the derivative shipped with openSUSE also can't be fully open, too. So there are only limited possibilities for the community to participate: via bugzilla, Novell doc comment system or via this list. Furthermore we welcome everyone who is willing to contribute for a certain topic on a case by case basis. Please also see the LSL announcement at the end of this mail. The XML sources are shipped with the opensuse distribution (therefore it is possible to send us patches), the DTD is available from NovellForge (see http://en.opensuse.org/Documentation_Team for details). The (majority) openSUSE documentation has a different approach. A lot of articles are designed to help with problems with specific hardware or configurations. Part of the documentation on openSUSE also present solutions for bugs or explain how to enhance the distribution and how to use unsupported stuff like, for instance, Xgl. Other articles illustrate the configuration of services not covered in the shipped manuals (e.g. setting up a mailserver). In the ideal case the openSUSE Wiki documentation is updated whenever there is need to. It is our (that is the documentation team) belief, that the documentation on the openSUSE Wiki is the ideal and indispensable complement. The fact that the openSUSE Wiki documentation is - at least theoretically ;-) - always "bleeding edge" is the main reason for the fact, that it is not shipped with the distribution. Some articles would probably already be outdated the day the iso images are published. For this very reason we stopped shipping the SDB (Support database) with S.u.S.E. Linux a few years ago. It is also our belief that it is absolutely necessary to have two different sources for documentation - a "static" one that is shipped with the distribution and a flexible one that is available online. In fact this is the case since at least S.u.S.E. Linux 4.2 (1996) when the SDB was born on www.suse.de. Thread summary -------------- (lines with my comments are starting with "# ") 1. Content ^^^^^^^^^^ 1.1 Documentation is not up-to-date due to the rapid development process and the fact that documenting software is not too popular with developers. 1.2 Version specific FAQs are missing 1.3 The software itself (man pages, help files etc.) is poorly documented. 2. Structure/Organisation ^^^^^^^^^^^^^^^^^^^^^^^^^ 2.1 A general concept on how to organise documentation on the openSUSE Wiki is missing. Solution 1 (Rajko): The structure should depend on the openSUSE versions - either use a directory based structure or name spaces # Lot's of documentation is not necessarily # version specific, so such a structure will # make it difficult to maintain such documents # This issue has been brought up frequently and I agree that it is # one of, if not _the_, most important issues that is to be solved # for opensuse.org. I would suggest to move this discussion to # opensuse-wiki, because there are more people participating in that # list and because it was brought up on that list in the past. It # was my plan to revitalise this discussion once the 10.2 # documentation is out the door (mid October) and the new starting # pages are in place (Oct 20th, hopefully). # In this context we should IMHO also discuss the search function, # because a wiki is not the best solution when you want to have # structured documentation. A real good search engine helps. # If you want me to start and moderate the discussion (as I did with # the starting page discussion), please give me another two weeks... 3. Participation ^^^^^^^^^^^^^^^^ 3.1 Motivation to contribute is low because the openSUSE Wiki documentation content is not shipped with the distribution. # See above - the main advantage of a Wiki article is the fact, that # it is always up-to-date (at least theoretically). It would make # little sense to ship documentation that is outdated. Please also # see the LSL announcementat the end of the mail - hopefully this is # a compromise you can live with. 3.2 SUSE keeps volunteers completely outside. We write our, they write their, and that's it. There is no joint effort, there is no coordination. It is not surprise that many people don't want to waste their time in disharmonious, inefficient effort. # Please see above and the LSL announcement below. 3.3 The SuSE documentation process needs to be public # Please see above and the LSL announcement below. 4. Tools ^^^^^^^^^ 4.1 A Wiki is a "content Motel" that makes it almost impossible to convert it contents to other formats (such as XML, for instance). A tool that produces a convertible source and is ridiculously easy to use is needed. Solution 1 (Sean): docbook::collab http://forge.joomla.org/sf/docman/do/listDocuments/projects.docbook_collab/docman.root # It is my strong belief, that a writer has to know the # document source format he is using inside out - otherwise he will # never ever produce data that is re-usable and convertible. This # does not only apply to TeX, XML and the like, but also to M$ Word, # OpenOffice and other tools. 4.2 We need a single tool that allows one to browse, read, edit, submit, proofread documentation and that has a workflow implemented. # You are looking for a Document Management System other than a # Wiki. Usually very expensive and not open source ;-) Project announcement: Lessons for Lizards ------------------------------------------ Triggered by Sean's mail in August (http://lists.opensuse.org/opensuse-doc/2006-08/) we (the documentation team) seriously started to think about how we could open up our processes an accept contributions from the community. As already said, existing processes make it impossible for us to open up our complete documentation. So we came up with the idea of a project we called "Lessons for Lizards". We initially planned to announce this project in December, because some basics (especially the xml to Wiki stylesheets) will not be ready until then. This thread made us rethink that decision. Nevertheless, the tools will not be ready before December... . Please tell us what you think about the project - nothing is carved in stone, yet. This is just a collection of ideas we came up with, so far. What is Lessons for Lizards (LSL)? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The idea behind Lessons for Lizards is to have a SUSE cookbook (cookbook is trademarked by O'Reilly, so we cannot use that name). It should contain recipes for certain tasks not covered in the printed manual, such as for instance "How to install and configure SUSE without YaST", "Setting up a mailserver", "Compiling a new Kernel", etc. (these topics are, of course, hypothetical - I hope you get the idea). It is our belief, that such a book is currently missing and would be very useful for many users. Who can contribute? ^^^^^^^^^^^^^^^^^^^^ Everybody who is willing to ;-). The documentation team is also willing to participate. Under which license will LSL be published? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Not decided, yet - proposals are welcome (should be an open source license, of course). Will LSL be shipped with the distribution? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Yes, it will be treated as the other manuals shipped with openSUSE. In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook). In which output formats will LSL be available? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ HTML, PDF, Wiki (more on Wiki below) What tools will Novell/SUSE provide? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * the complete build environment SUSE uses to build it's books (including stylesheets, scripts, etc.) as an RPM package * a SVN server on which the LSL sources are hosted (read/write access for everybody) * a style guide * support (on this mailing-list) I have already written articles that would fit into the book on the wiki. What about them? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The SUSE documentation team is willing to manually convert each Wiki article that would fit into the book into docbook xml. Authors may contact us through this list. How can I make sure my article is updated in both the wiki and the book? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ toms, our xsl guru, has written stylesheets that convert docbook xml into Wiki language, so the xml source would be the single source to produce Wiki and "LSL output". At the moment. these stylesheets are work in progress and the Wiki output needs to be beautified manually. We hope to have a better version available in December. If you would like to help us with these stylesheets, please contact my by mail. -- Regards Frank Frank Sundermeyer, SUSE LINUX GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.novell.com/ "Reality is always controlled by the people who are most insane" Dogbert --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
