Mailinglist Archive: opensuse-doc (40 mails)

< Previous Next >
Re: [opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
  • From: Rajko M <rmatov101@xxxxxxxxxxx>
  • Date: Sun, 01 Oct 2006 05:03:48 -0500
  • Message-id: <451F9284.10907@xxxxxxxxxxx>
jdd wrote:
> Rajko M a écrit :
>
>> The YaST and a company, is resting primarily with Novell/SUSE doc team.
>
> but is still poorly documented, as SuSE folks focused on the
> administrator guide on general Linux infos (making probably the better
> book ever on the subject)

Basic problem with Linux, including SUSE, is that, even if there is
dedicated team, document writers never had enough time to do their job.

Detailed program description without examples is few times bigger text
than program itself, and it takes more time to write it. The description
is just base document and it can be used to write all other readme,
guides, etc.

Writing all documents straight from a source code is just as bad idea as
writing program before you define what you want to do with it and tools
that you need to achieve goals.

>> process is still missing clear structure. Where to pick up source, (...)

Misunderstanding.
I talk about writing and submission *process structure* not
documentation structure. Besides wiki, I have n o clear idea how SUSE
documentation process works.

How one volunteer can help writing documentation if he/she has no idea
where to start without interfering with SUSE process.

What I see now is that they keep 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.

....
> Of course it's very usefull, certainly necessary, but the structure I
> speak of is the organisation of the documentation itself. what chapters,
> what titles, what page names (for the wiki), what categories...
>
> we all worked on that one day or an other, but the result is still very
> unperfect, I know of pages I can't find again (even page I did write
> myself :-()
>
> Part of the solution is probably to work on the wiki (as a base tool)
> like if it was a book. that is no search engine, no google, but as many
> Table of Content/index as we want.
>
> once this structure well formed (and the "portal" sub structure is a
> good example), it should be looked for portals administrators.
>
> The only way to have a page up to date is to have one author responsible
> of that. This don't mean this page (portal) admin have to write all
> himself, on the contrary he should have only to manage the pages (as in
> "manage a team")

Long time ago I wrote this:
We need volunteers to lead projects, give shape, define tasks, be a
focal point of project development. Loose groups waste a lot of energy
for duplicated efforts. (http://en.opensuse.org/Tasks)

> Think of docbook "chapters", "articles", "titles". any body can write
> articles in a semi informal manner, given somebody gives the shape.
>
> 25 years ago, my wife wrote a "memoire" (white paper) about computer
> aided english teaching. At that time I had only scholar english and she
> had a master :-), but I'm not too bad as organisation. so I took it's
> work, asked her the good questions and organised the document. It's a
> very interesting experience to organise a document you nearly don't
> understand
>
> Our goal now is similar, but the document is much bigger, the author
> nearly impossible to have at hand (and I have 25 years more :-(), so the
> task is very difficult.
>
> but, in fact, we don't have to do this right now for an exam. It will go
> it's pace, slowly, and we can hope the result will be better and better
> when the time passes :-)
>
> jdd
>

Can I take that you are taking ownership of Administration Portal (or
Index)?

--
Regards,
Rajko.
Visit http://en.opensuse.org/MiniSUSE
---------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >
List Navigation
This Thread
Follow Ups
References