Mailinglist Archive: opensuse-doc (40 mails)

< Previous Next >
Re: [opensuse-doc] Thread summary and announcement [was:The openSUSE distribution chages are way ahead of documentation?]
  • From: Rajko M <rmatov101@xxxxxxxxxxx>
  • Date: Sun, 8 Oct 2006 11:19:40 -0500
  • Message-id: <200610081119.40724.rmatov101@xxxxxxxxxxx>
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 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
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
> # 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
> ( 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)



Rajko M.
To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >