On Thursday 05 October 2006 11:02, Frank Sundermeyer wrote:
Hi,
Hello Frank :-)
this thread took many twists and turns,
Just as any discussion about problem that has no simple solution, and actually has not only one soution, but many of them, and parties can't meet and discuss topic before it goes public. So ideas are mentioned, and discarded as they show as unpractical. ...
Shipped manuals vs. openSUSE wiki ---------------------------------
Current state is, that we have two kinds of documentation for the openSUSE distribution:
* shipped manuals * openSUSE wiki
My concern, and reason to start the thread is not to criticize anybody as I was able to imagine how it works, and your explanation just confirmed that. I was looking at documentation problem in Linux that is transfered to SUSE. A lot of obsolete, inaccurate, sparse documentation, lack of examples how to use applications. There is huge pile of documentation to read, check accuracy and completness, contact original authors, see where they want to go. ....
Thread summary 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.
This is about any Linux documents. Some projects keep up, the other not. The speed of changes, including SUSE distribution, is so fast that no one can tell that certain package will be in the next release. That demotivates people to even try to review documents, and even lesser to add content.
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
If we would use indexes, instead of Categories, or subpages, than keeping articles grouped by architecture, than by version is viable, and much better alternative than present status, where even frequent visitors to wiki are surprised that some article is written, some other is just a stub, and sometimes under nice title is just "This page is under construction".
# 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...
We can discuss Wiki organization and part of documents that will be placed there, on opensuse-wiki, but methods to synchronize code development and documentation writing, are still better to discuss here. It should be permanent effort, to change developers ideas about documentation importance. That effort should not be limited to distribution, as SUSE is already documented better than then the rest. It has to go out and bug software developers to provide more details.
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.
I agree that wiki is good to offer fast solution for burning problem, but to limit it deliberately only to that function, is not good in the world where online resources are first that user try to find once the system is up and running. It is also necessary to have classic books, for the time and cases where online is not available, for the functions that doesn't change much with the time. The Lesson for Lizards is fancy name, but it will not change need for documentation organization structure, as well as page structure and formating. The kind that is not necessary to learn much to understand and contribute. That is another reason for thoughts about WYSWYG editor tools. How that would work? Download template for article that you write, fill all fields, and you have good looking article, with all sections included. Upload it to wiki. Done.
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.
This was really complaint about Wiki articles and the way it works. Basic is that some coordination must exist. I bet that there will be more volunteers if each would be able to pick some task from list, not to wonder all over the place in order to find something to do.
# Please see above and the LSL announcement below.
3.3 The SuSE documentation process needs to be public
^ :-) Novell - SUSE - openSUSE. I just noticed. You are talking about Novel and SUSE, and only wiki is openSUSE. I just save few strokes "open" if I say SUSE.
# 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.
The writer has to know the tools and what is possible to do with them, but need to know source format tells that tools are missing.
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 ;-)
I thought something that can mimic such system. For software that works like: Download existing source, change it, submit patches for review. Done. Similar for new sources. The only thing that doesn't exist is task execution control that is needed in environments where people get paid for the work done.
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)
Good. ... -- Regards, Rajko M. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org