The openSUSE distribution chages are way ahead of documentation?

classic Classic list List threaded Threaded
47 messages Options
123
Reply | Threaded
Open this post in threaded view
|

The openSUSE distribution chages are way ahead of documentation?

Rajko M.
Versions of suse are coming in so fast pace that documentation writers
and translators have no chance to follow the changes, and that is for
sure systematic error that is taken over from Linux (open source)
development process.

It is obvious from amount of changes that are introduced almost daily
that nobody has in mind that documentation is part of software, just as
much as source code and binaries. There is no successful open source
project that failed to deliver documentation.

We all like to mention some well documented projects like Samba, but
when it comes to do the same, we have problem to deliver easy to read
documents. The example that came in mind is very important article
http://en.opensuse.org/Additional_YaST_Package_Repositories
that must have different links for each version and is written as single
page with some notes for 10.0 and 10.1 that resemble more on C defines
that on human readable text.

Missing general FAQ, as well as one for each version, that is easy to
reference in support effort on mail lists and Usenet groups (forums).

Actually missing general concept how to organize documentation is
probably the worst of all problems.

One idea to start from is to use as base SUSE version, just as it is
given on download sources.
Why?
Because there is logical explanation and a technical reason to sort FTP
server directories first by computer architecture, second by SUSE
version, than to have installation sources, additional sources, updates,
etc.

What is the best method to publish that kind of document structure?
What is the best way to bring documents and packages together?
Would be the directory structure good, as it allows to bring in the same
directory our own contributions with original author manual pages, help
files etc. It will make easier to see where original software
documentation is short and add more content instead of starting from
scratch every time.

Mediawiki software that is structured to support well Wikipedia type of
data that has not many similar articles that differs only in few lines.
Is the usage of structure:
 opensuse.org/10.0/
 opensuse.org/10.1/
 opensuse.org/10.2/
appropriate, or it is better to use name spaces?

Please add your comments and ideas.
Helping to organize documentation is just as important as to bring in
the latest software version.

--
Regards,
Rajko.
Visit http://en.opensuse.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Alexey Eromenko
I believe that in order to solve documentation problem, community must help.

In order for the community to help, we need tools - that is wiki (which exists on the webpage) *and* a conversion tool to convert that wiki to RPM to install offline.
There is *no* such conversion tool available, and so it makes me much less interested to contribute to wikis, because they are not installed in the final distro.

I agree to contribute more articles to our openSUSE wiki *only* if Novell agrees to distribute this as RPM on the standard openSUSE DVD ISO.


Until today I have contributed few items: such as "FreeNX" server & "Qemu" configuration articles to wiki, but those are not included in the final distro, which makes me very unhappy about continuing contribution...

To Novell: please allow the community to write docs, that will be included in the distro  for offline use (in RPM package, HTML format).

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Sean Wheller
In reply to this post by Rajko M.
On Saturday 30 September 2006 10:53, Rajko M wrote:
> Please add your comments and ideas.
> Helping to organize documentation is just as important as to bring in
> the latest software version.

Rajko its worse than that.

SuSE documentation sources are not in a revision control repo despite the fact
that such a repo was setup. As such there is a barrier to entry for open
collaboration and contribution on documentation sources.

Once SuSE documentataion process embraces the open source workflow and
provides the infrustructure to support it, then the collective eye and brain
of the community can assist the doc team who at this point are just
developing in a hole.

To fix the problems you mention in a manner that is sustainable, we need to
address the above first. Then community and doc-team can move forward
together and discuss how this is going to work and what we can do to address
problems, make life easier.

Translators need input also and implimentation of the pot/po file format
generated from Docbook XML and places in a batch environment using diff etc
can help to reduce the workload.

Hope this helps,

--
Ask me about the Monkey.

Sean Wheller
Technical Author
[hidden email]
+27-84-854-9408
http://www.inwords.co.za
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Sean Wheller
In reply to this post by Alexey Eromenko
On Saturday 30 September 2006 11:03, Alexey Eremenko wrote:

> I believe that in order to solve documentation problem, community must
> help.
>
> In order for the community to help, we need tools - that is wiki (which
> exists on the webpage) *and* a conversion tool to convert that wiki to RPM
> to install offline. There is *no* such conversion tool available, and so it
> makes me much less interested to contribute to wikis, because they are not
> installed in the final distro.
>
> I agree to contribute more articles to our openSUSE wiki *only* if Novell
> agrees to distribute this as RPM on the standard openSUSE DVD ISO.
>
>
> Until today I have contributed few items: such as "FreeNX" server & "Qemu"
> configuration articles to wiki, but those are not included in the final
> distro, which makes me very unhappy about continuing contribution...
>
> To Novell: please allow the community to write docs, that will be included
> in the distro  for offline use (in RPM package, HTML format).

I agree with the sentiments of your message.

However, I am not a lover of wiki. Wiki is a content Motel. everything
check-in, but nothing ever checks out. Porting wiki to more useful formats
such as Docbook XML or DITA is a RPITA and adds an additional step in the
process of packaging.

However, I do agree that a web-based solution does reduce the barrier to entry
for just anyone who wants to contribute something in the way of docs. One
idea I have been playing with is th evision of editing Docbook under a
web-based editor. So giving wiki-like docbook editing capabilities.

This could help eliminate the problem of preprocessing wiki stuff to Docbook.
If the source remains as docbook it would also make integration with the
current toolchain used by the doc team much easier. It would also enable
people that donot want to use a wiki-like enviroment, to edit the docbook src
as a working copy of SVN. In short the level of indirection between editing
environments would be greatly improved.

There is a project that is a Joomla component, called docbook::collab. This
demonstrates the direction I am thinking in. However, docbook::collab
currently has some retrictions.
1. It uses BitFlex Editor. This supports creation of sdocbook. OK you can
import full-docbook, but only edit using sdocbook.
2. It stores documents in MySQL. Not he best place to have these resources if
you want SVN and piping into the build and translation processes.

Perhaps people could look at this type of solution?

--
Ask me about the Monkey.

Sean Wheller
Technical Author
[hidden email]
+27-84-854-9408
http://www.inwords.co.za
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

jdd@dodin.org
In reply to this post by Alexey Eromenko
Alexey Eremenko a écrit :

> To Novell: please allow the community to write docs, that will be
> included in the distro  for offline use (in RPM package, HTML format).
>
as a very lon time linudoc contributor, I know quite well
the problem, but have no simple solution :-(

A goos documentation have to be well organised/structured
and this is simply not the ordinary way of thinking of most
people.

Wikipedia IS a very good information source, but not so well
organised (and can't be better, probably).

SuSE manuals used to be very good, thanks to a very good
writing team (and probably very expensive too).

The goal should be to have a much bigger (with tranlations)
  documentation with nearly the same money. I do not have a
solution. CVS or SVN are of course a good step forward.

writing and translating doc is a very hard work, and even
more as a voluntary work - I myself took some vacation from
suse documentation for a month now, exausted by 6 month of
continuous work.

the truth is that documentation should be written 3 month
ahead of the final product (for translating and printing
delays) and this is quite impossible if we always wan to
freeze the distro at the last minute

jdd

--
http://www.dodin.net
http://dodin.org/galerie_photo_web/expo/index.html
http://lucien.dodin.net
http://fr.susewiki.org/index.php?title=Gérer_ses_photos
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rajko M.
jdd wrote:
> Alexey Eremenko a écrit :
>
>> To Novell: please allow the community to write docs, that will be
>> included in the distro  for offline use (in RPM package, HTML format).

That would be one solution too. Included rpm for HowTo is probably
example of the way you would like to have wiki articles. Take Mediawiki
software output, strip it to the bare minimum, and put in packages.

> as a very long time linudoc contributor, I know quite well the problem,
> but have no simple solution :-(
>
> A good documentation have to be well organised/structured and this is
> simply not the ordinary way of thinking of most people.

Right.
The problem is that current core team are all (or majority) software
developers (programmers). They know what software will do (most of the
time), and for them is hard to imagine how far is few notes that one get
with --help option from usable instructions how to use software.

> Wikipedia IS a very good information source, but not so well organised
> (and can't be better, probably).

I'm afraid that everybody is expecting too much from wiki self
organizing and healing. It is fine for Wikipedia where you don't have
demand for articles (descriptions, instructions) to be in sync with
anything.

With openSUSE wiki that doesn't work as article about program can't
follow 2 years after program is written. It has to be published in the
same time as software, and updated every time developer changes program.

> SuSE manuals used to be very good, thanks to a very good writing team
> (and probably very expensive too).

For me, that was one of the reasons to stay with SUSE so long.
I can remember the style was excellent for the beginner and advanced
user as well.

> The goal should be to have a much bigger (with tranlations)
>  documentation with nearly the same money. I do not have a solution. CVS
> or SVN are of course a good step forward.

The SVN is good step if you have tools and documentation how to use them.
Step by step explanation how to check out, how to submit changes, what
tools to use to edit. Documentation about this tools used in specific
SUSE environment. Yes, documentation about how to contribute
documentation trough SVN and other means would be super.

> writing and translating doc is a very hard work, and even more as a
> voluntary work - I myself took some vacation from suse documentation for
> a month now, exausted by 6 month of continuous work.

I can see that :-D

> the truth is that documentation should be written 3 month ahead of the
> final product (for translating and printing delays) and this is quite
> impossible if we always wan to freeze the distro at the last minute
>
> jdd
>

That will keep happening as long as programmers will think that the job
is done when they are done.

The plain truth that takes in account only physical activity (not
thinking how to write something) is that program source code is
condensed explanation what program will do, so to write documentation
one needs more time than program writer.

How much more?
I would say few times more just to explain program structure, input and
output data structure of functions, what are limitations of used
algorithms (like where it is optimal to use), examples of usage.

For occasional contributors, document writers, we would need templates
or even forms easy to fill in. This way there will be mentioned all that
is necessary to know about program.

--
Regards,
Rajko.
Visit http://en.opensuse.org
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rajko M.
In reply to this post by Sean Wheller
Sean Wheller wrote:

> On Saturday 30 September 2006 11:03, Alexey Eremenko wrote:
>> I believe that in order to solve documentation problem, community must
>> help.
>>
>> In order for the community to help, we need tools - that is wiki (which
>> exists on the webpage) *and* a conversion tool to convert that wiki to RPM
>> to install offline. There is *no* such conversion tool available, and so it
>> makes me much less interested to contribute to wikis, because they are not
>> installed in the final distro.
>>
>> I agree to contribute more articles to our openSUSE wiki *only* if Novell
>> agrees to distribute this as RPM on the standard openSUSE DVD ISO.
>>
>>
>> Until today I have contributed few items: such as "FreeNX" server & "Qemu"
>> configuration articles to wiki, but those are not included in the final
>> distro, which makes me very unhappy about continuing contribution...
>>
>> To Novell: please allow the community to write docs, that will be included
>> in the distro  for offline use (in RPM package, HTML format).
>
> I agree with the sentiments of your message.
>
> However, I am not a lover of wiki. Wiki is a content Motel. everything
> check-in, but nothing ever checks out. Porting wiki to more useful formats
> such as Docbook XML or DITA is a RPITA and adds an additional step in the
> process of packaging.

The Docbook is marked as default format, but I've never seen any editor
mentioned that will help document writers to concentrate on writing, not
on learning of document source format, and all other stuff like
conversion methods to different formats, that has little to do with
actual writing.

> However, I do agree that a web-based solution does reduce the barrier to entry
> for just anyone who wants to contribute something in the way of docs. One
> idea I have been playing with is th evision of editing Docbook under a
> web-based editor. So giving wiki-like docbook editing capabilities.

Editor? Like mentioned above.

> This could help eliminate the problem of preprocessing wiki stuff to Docbook.
> If the source remains as docbook it would also make integration with the
> current toolchain used by the doc team much easier. It would also enable
> people that donot want to use a wiki-like enviroment, to edit the docbook src
> as a working copy of SVN. In short the level of indirection between editing
> environments would be greatly improved.
>
> There is a project that is a Joomla component, called docbook::collab. This
> demonstrates the direction I am thinking in. However, docbook::collab
> currently has some retrictions.
> 1. It uses BitFlex Editor. This supports creation of sdocbook. OK you can
> import full-docbook, but only edit using sdocbook.
> 2. It stores documents in MySQL. Not he best place to have these resources if
> you want SVN and piping into the build and translation processes.
>
> Perhaps people could look at this type of solution?
>

I hope they will. Though except small intro I wasn't able to find (guess
what) documentation:
http://forge.joomla.org/sf/docman/do/listDocuments/projects.docbook_collab/docman.root

In the meantime we can think about what else we would need.
- The templates and forms as a help for occasional contributors is what
we are missing right now.
- The tools (ways) to announce that we plan work on some documents, the
searchable database of already active projects, and their status.
This will give us ability to see active, stale and unmaintained
projects. Projects that need help. The idea is pretty much the same as
sourceforge.net, but with focus on SUSE related aspects.
- The categorization, naming structure.
I started that, jdd started that, and everything didn't moved from the
beginning. If you ask me for the links, I lost even that. It is on the
openSUSE wiki :-)  (this sounds as helpful, as many help files)



--
Regards,
Rajko.
Visit http://en.opensuse.org
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Andreas Jaeger

Just a short remark to this thread:

Novell has a documentation team working on our manuals, nothing has
changed here (see http://en.opensuse.org/Documentation_Team).  It's
not developers writing manuals, it's dedicated editors - some of them
coming from development and others from other areas.

Since we have a holiday on tuesday, most of us take a long weekend
(monday of as well), so don't expect direct feedback on this by the
documentation team.

Somebody mentioned that software is only finished at the end - this is
not completely true since openSUSE.  My goal is to get features in
early so that they can be tested and documented early.  It's still
very tight for the documentation team but it was even worse before;-(.

Cheers,
Andreas
--
 Andreas Jaeger, [hidden email], http://www.suse.de/~aj/
  SUSE Linux Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

attachment0 (194 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

jdd@dodin.org
In reply to this post by Rajko M.
Rajko M a écrit :

> - The categorization, naming structure.
> I started that, jdd started that, and everything didn't moved from the
> beginning. If you ask me for the links, I lost even that. It is on the
> openSUSE wiki :-)  (this sounds as helpful, as many help files)

the true problem is _not_ the editor, but the structure.

As you may know, generating docbook with a text processor is
like generating a program from a program generator: a mess

even a wiki can do a very good job as documentation
generator, given the pages are related to a structure.

but everybody have seen the time necessary to have a front
page (we don't have it yet? sorry for that :-) and
meaningfull menus :-). not to mention the same debate on the
"documentation" page :-).

practically, I'm stuck on the last but one chapter of
Starcraft Broodwar and if I can't defeat the Protos, what
seems  likely, I will come back here :-)

First of all, we must make the difference between the
openSUSE native applications, generally called YaST (but
also Zen...) and the more general applications.

We must focus on yast, because nobody else will do it for us :-)

So can anybody list exacltly the products of this kind
remaining on the 10.2 openSUSE? (Yast, SaX2, Zen,
SUSEFirewall2, SIGA, SUSEConfig... ?)

to be constructive, I opened a sub chapter in the
documentation page:

http://en.opensuse.org/Documentation#openSUSE_internals_Documentation

(this page should really have a TOC. I commented the NOTOC
tag in the page source, uncomment it if you want)

jdd

--
http://www.dodin.net
http://dodin.org/galerie_photo_web/expo/index.html
http://lucien.dodin.net
http://fr.susewiki.org/index.php?title=Gérer_ses_photos
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rüdiger Steffan
Hello,
I am Ruediger Steffan, located in Germany, and would like to volunteer in writing and/or translating documentation.
My job is customer advisor for telecommunication and DSL. In spare time I am distance-studying industrial engeneering and will start with degree dissertation in spring 2007.
It would be nice to hear from you and get some hints where to start.

Greets,
Ruediger
Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rajko M.
In reply to this post by Andreas Jaeger
Andreas Jaeger wrote:

> Just a short remark to this thread:
>
> Novell has a documentation team working on our manuals, nothing has
> changed here (see http://en.opensuse.org/Documentation_Team).  It's
> not developers writing manuals, it's dedicated editors - some of them
> coming from development and others from other areas.
>
> Since we have a holiday on tuesday, most of us take a long weekend
> (monday of as well), so don't expect direct feedback on this by the
> documentation team.
>
> Somebody mentioned that software is only finished at the end - this is
> not completely true since openSUSE.  My goal is to get features in
> early so that they can be tested and documented early.  It's still
> very tight for the documentation team but it was even worse before;-(.
>
> Cheers,
> Andreas

Thanks for the response Andreas.

I know that developers don't write documentation, at Novell, but in the
most of small projects they do, and that is where serious improvement is
needed. Novell/SUSE guys are trying hard to bring people in, but still,
one needs too much to learn before can start contributing.

One preconfigured package/pattern that contains all available software
for documentation writing, for instance SVN with links to Novell
repositories, editor with Novell like templates, and probably much more,
will make volunteers life easier and move focus from tools to content.

I hope that documentation guys will have some answers, instructions,
ideas, as we need some in order to get involved.

My idea of ideal world of documentation writer is one browser where one
can read existing manuals, howto's etc, than when something was found
start editor and change document. When done, submit for approval,
proofreading and that's it. After some time get feedback, if it is
accepted or not, or in need of further changes additions.

In this world somebody else will think how to structure whole
documentation, where to move balance, how to name articles.

--
Regards,
Rajko.
Visit http://en.opensuse.org
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rajko M.
In reply to this post by jdd@dodin.org
jdd wrote:
> Rajko M a écrit :
>
>> - The categorization, naming structure.
>> I started that, jdd started that, and everything didn't moved from the
>> beginning. If you ask me for the links, I lost even that. It is on the
>> openSUSE wiki :-)  (this sounds as helpful, as many help files)
>
> the true problem is _not_ the editor, but the structure.

I agree. That is what I can't get right, the idea, how to organize all.
For the God knows what time, I'm stuck trying to find out how to
structure articles in one complex group of articles, this time it is
about Troubleshooting ( http://en.opensuse.org/User:Rajko_m/Tests ), and
I really need professional writer advice how to overcome this.

> As you may know, generating docbook with a text processor is like
> generating a program from a program generator: a mess

As usually in the life, tool doesn't do the job, but human using it.

> even a wiki can do a very good job as documentation generator, given the
> pages are related to a structure.

I agree. One important point is to see specifics of openSUSE related
articles, and see what tools on the wiki are the most appropriate.

> but everybody have seen the time necessary to have a front page (we
> don't have it yet? sorry for that :-) and meaningfull menus :-). not to
> mention the same debate on the "documentation" page :-).

The debate about front page is open, the only problem is that we have to
decide about purpose of the front page, and set limits on number of
items that we want to introduce.

> practically, I'm stuck on the last but one chapter of Starcraft Broodwar
> and if I can't defeat the Protos, what seems  likely, I will come back
> here :-)

:-D  Serious problem.

> First of all, we must make the difference between the openSUSE native
> applications, generally called YaST (but also Zen...) and the more
> general applications.
>
> We must focus on yast, because nobody else will do it for us :-)

The YaST and a company, is resting primarily with Novell/SUSE doc team.
For sure, we can help translating to languages that we know, but the
process is still missing clear structure. Where to pick up source, what
tools to use, where to deliver results for approval, who will give
feedback to volunteer, what kind of feedback, etc. Actually, the same
process, once defined, can be applied to any documentation, not only
YaST related.

> So can anybody list exactly the products of this kind remaining on the
> 10.2 openSUSE? (Yast, SaX2, Zen, SUSEFirewall2, SIGA, SUSEConfig... ?)

Let we try, and see what doc and devel guys can add/subtract.

> to be constructive, I opened a sub chapter in the documentation page:
>
> http://en.opensuse.org/Documentation#openSUSE_internals_Documentation
>
> (this page should really have a TOC. I commented the NOTOC tag in the
> page source, uncomment it if you want)
>
> jdd
>


--
Regards,
Rajko.
Visit http://en.opensuse.org/MiniSUSE
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rajko M.
In reply to this post by Rüdiger Steffan
Ruediger Steffan wrote:

> Hello,
> I am Ruediger Steffan, located in Germany, and would like to volunteer
> in writing and/or translating documentation.
> My job is customer advisor for telecommunication and DSL. In spare time
> I am distance-studying industrial engeneering and will start with degree
> dissertation in spring 2007.
> It would be nice to hear from you and get some hints where to start.
>
> Greets,
> Ruediger

As you can see Steffan, we are discussing where to start, so if you have
 will to help, watch this thread, and links that we refer to. That way
you can make your own idea where are the problems, and what would be
good to do. Editing help on wiki is always welcome.

The main tool for now is openSUSE wiki at http://en.opensuse.org, and as
native German speaker, you may find interesting http://de.opensuse.org .
Jean (jdd) added some links to the:
http://en.opensuse.org/Documentation#openSUSE internals Documentation
so you can login to wiki and start writing articles.

--
Regards,
Rajko.
Visit http://en.opensuse.org/MiniSUSE
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rajko M.
Rajko M wrote:
....

> Jean (jdd) added some links to the:
> http://en.opensuse.org/Documentation#openSUSE internals Documentation
> so you can login to wiki and start writing articles.
>
Sorry for the link. It should be:
http://en.opensuse.org/Documentation#openSUSE_internals_Documentation

--
Regards,
Rajko.
Visit http://en.opensuse.org/MiniSUSE
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

jdd@dodin.org
In reply to this post by Rajko M.
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)

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

this is not structure in the way I mean it. This is tools.

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")

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" (wite 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

--
http://www.dodin.net
http://dodin.org/galerie_photo_web/expo/index.html
http://lucien.dodin.net
http://fr.susewiki.org/index.php?title=Gérer_ses_photos
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rajko M.
In reply to this post by Rajko M.
jdd wrote:
> What do you think of using the administrator guide layout to create a
> wiki index? that is taking the Guide titles, chapters, creating wiki
> pages accordingly and filling the page with links or meaningfull content
> (not the book content, but addons)?
>
> This would make the book very usefull as it's users could come on the
> wiki with already a knowledge
>
> if we do so, it should be usefull to open a new thread on this subject

I agree.

1) Somebody, that had more time dedicated to the task, spent time to
design book layout and structure.
2) It was perfected (polished) trough the years.
3) It will be helpful to keep the same layout in both, book and wiki.

It is always good not to reinvent hot water :-)

--
Regards,
Rajko.
Visit http://en.opensuse.org
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rajko M.
In reply to this post by jdd@dodin.org
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

jdd@dodin.org
Rajko M a écrit :

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

admin is too large a goal :-) and I have already the task of
admin of fr.opensuse.org, so I would like to let to others
the portal administration

of course I can and will participate. The french wiki lives
now without my constant attention :-) and I will participate
more in english one.

but like I said, it's probably better to begin with yaST
tools documentation

jdd

--
http://www.dodin.net
http://dodin.org/galerie_photo_web/expo/index.html
http://lucien.dodin.net
http://fr.susewiki.org/index.php?title=Gérer_ses_photos
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Christian Boltz-5
In reply to this post by Rajko M.
Hello,

Am Samstag, 30. September 2006 10:53 schrieb Rajko M:
[...]
> Mediawiki software that is structured to support well Wikipedia type
> of data that has not many similar articles that differs only in few
> lines. Is the usage of structure:
>  opensuse.org/10.0/
>  opensuse.org/10.1/
>  opensuse.org/10.2/
> appropriate,

This structure makes it hard to place pages that are valid for
multiple releases - you'll at least need lots of redirects
("/10.2/sometopic -> /10.1/sometopic")

I'd vote for opensuse.org/sometopic/10.0 (and opensuse.org/sometopic
for version-independend texts).

If the changes are small, you can also do "inline versioning" by writing
"in SUSE Linux 10.1, ...." or using the Template:VersionNote.

Well, I'm afraid there is no perfect solution for multi-version
documentation, but there are better and worser ones ;-)

> or it is better to use name spaces?

No, I don't think so - namespaces ("10.1:sometopic") have the same
problem I already explained for /10.1/sometopic.

If you want, you can additionally use categories ("Category:10.1")
because this way allows articles to be valid for multiple versions -
but keep in mind that you'll have to add another category
("Category:10.2") to all artices that are still valid in 10.2. (Yes,
many things change, but even more things do not change - so this will
cause lots of work ;-)


Regards,

Christian Boltz
--
Kurz gefasst:  /etc/crontab ist IMHO so nützlich wie eine Laus in
einem Raumanzug - es juckt, aber Du kannst Dich nicht kratzen, es
sei denn, Du bist Gott auf Deinem System. Und dann weisst Du noch
nicht mal, ob Du anstelle der Laus Deine Nase amputiert hast.
[Jan Trippler in suse-linux]
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: The openSUSE distribution chages are way ahead of documentation?

Rajko M.
Christian Boltz wrote:

> Hello,
>
> Am Samstag, 30. September 2006 10:53 schrieb Rajko M:
> [...]
>> Mediawiki software that is structured to support well Wikipedia type
>> of data that has not many similar articles that differs only in few
>> lines. Is the usage of structure:
>>  opensuse.org/10.0/
>>  opensuse.org/10.1/
>>  opensuse.org/10.2/
>> appropriate,
>
> This structure makes it hard to place pages that are valid for
> multiple releases - you'll at least need lots of redirects
> ("/10.2/sometopic -> /10.1/sometopic")
>
> I'd vote for opensuse.org/sometopic/10.0 (and opensuse.org/sometopic
> for version-independend texts).
>
> If the changes are small, you can also do "inline versioning" by writing
> "in SUSE Linux 10.1, ...." or using the Template:VersionNote.
>
> Well, I'm afraid there is no perfect solution for multi-version
> documentation, but there are better and worser ones ;-)
>
>> or it is better to use name spaces?
>
> No, I don't think so - namespaces ("10.1:sometopic") have the same
> problem I already explained for /10.1/sometopic.
>
> If you want, you can additionally use categories ("Category:10.1")
> because this way allows articles to be valid for multiple versions -
> but keep in mind that you'll have to add another category
> ("Category:10.2") to all artices that are still valid in 10.2. (Yes,
> many things change, but even more things do not change - so this will
> cause lots of work ;-)
>
>
> Regards,
>
> Christian Boltz

Thanks for the comment Christian.

That was a day ago when I was asking this :-)
I was looking for some idea, and I wasn't really convinced that either
mentioned in that post was good.

There is no perfect solution if one looks to achieve multiple goals.
I would set primary goals to:
- easy to find for anyone, (including me :-) ) and
- easy for article writers.

If that are prim directives, than more work is granted, whatever
structure will be.
Someone has to go after article is written and do some proofreading,
formating, indexing etc. That is how that works in any branch of
publishing, we can't expect that the same rules doesn't apply to us.

Indexes (or Portals) are the easiest way to organize content. I prefer
word Index as it is the same data structure, with the same purpose like
the book index. Portals have the same purpose with added content, so
once we have Index we can design portal.
Why not to add articles to categories?
I can search and link in index few pages for the time that I need to add
category to one article. I tried to add categories before, and I did
indexing too. It is lesser work with additional benefit that Index(es)
can have more different layouts without touching underlaying software.

Categories are good for Wikipedia type and amount of data, but as you
mentioned it is too much work to do the same for software distribution.

--
Regards,
Rajko.
Visit http://en.opensuse.org
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

123