Mailinglist Archive: opensuse-doc (14 mails)

< Previous Next >
[opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
  • From: Rajko M <rmatov101@xxxxxxxxxxx>
  • Date: Sat, 30 Sep 2006 03:53:32 -0500
  • Message-id: <451E308C.9010501@xxxxxxxxxxx>
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: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >
List Navigation