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(a)opensuse.org
For additional commands, e-mail: opensuse-doc+help(a)opensuse.org
Hi,
we like to announce the alpha release of "susedoc", a toolkit the
SUSE doc team develops and uses to build the SUSE documentation,
released under the GPL. The RPM package contains makefiles and
stylesheets for HTML, XSL-FO and Wiki. See
10.0
http://software.opensuse.org/download/home:/thomas-schraitle/SUSE_Linux_10.…
10.1
http://software.opensuse.org/download/home:/thomas-schraitle/SUSE_Linux_10.…
1. Features
-----------------------------------------------
* Validates your XML sources
* Contains Python script to create a working sandbox with all
necessary files.
* Creates HTML, PDF and Wiki with a simple make command
* Supports handling of conditional text in XML (aka "profiling")
* Supports XEP, FOP planned
2. Requirements
-----------------------------------------------
* libxml2, libxslt
* inkscape
* transfig
* ImageMagick
* java
* xml-commons-resolver
* docbook-xsl-stylesheets
* svg-dtd
* freefont
* fop or xep
3. Restrictions
-----------------------------------------------
* At the moment you can not build PDFs with our customized stylesheets
due to restrictions on the FOP side (we use XEP.). However, it is
possible to use the original DocBook XSLT stylesheets.
* Wiki stylesheets are a "work in progress". Small chapters or
articles should work but whole books needs more work.
* Documentation can be improved. ;)
4. Quickstart
-----------------------------------------------
With the help of susedoc-new.py after installation you can create
a "Hello World" sandbox where you can play with, for example:
$ susedoc-new.py -d docbook_44
This creates a directory "susedoc-xmltest" where you can find all the
needed files. To create HTML, run "make html". For more information,
see "susedoc-xmltest/README" or use "make help".
For the next weeks I am on vacation. If you have questions please
contact Frank Sundermeyer. :)
Have fun!
Tom
--
Thomas Schraitle
----------------------------------------------------------------------
SUSE LINUX GmbH >o) Documentation Specialist
Maxfeldstrasse 5 /\\
90409 Nuernberg _\_v http://en.opensuse.org/Documentation_Team
---------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org
For additional commands, e-mail: opensuse-doc+help(a)opensuse.org
On Tuesday 03 October 2006 20:22, linux_learner wrote:
> The problem is, we have more developers than documenters. Even the
> documentation of smart on opensuse.org is quite pathetic. I wrote the
> smart howto here
> http://wiki.suselinuxsupport.de/wikka.php?wakka=HowtoSmartPackageManager
> I just don't know how to import it into opensuse.org
It shouldn't be a problem.
The opensuse version was just a stub (name for incomplete article), that
should be compelling for someone to write more. As I can see you already
started. I formated it and edited a bit.
> The documentation on rug just plain sucks. I started to document it,
> but then the guy hosting my site went down, and I lost the wiki
> database. I was about half way done with the rug portion of it.
It happens.
Keep your page sources locally, just in case.
> YaST, as y'all have discussed, is severly under documented.
That is to the some extent right. Please look at the collection on:
http://en.opensuse.org/YaST_Documentation_Portal
This is rough digest of all articles listed with search for yast, rug, zmd,
and libzypp. I know it could be better, but right now I'm trying to index all
pages in a few categories and call for help to move things around until
(almost) everybody is satisfied.
Why not mediawiki built in categories?
It is much faster to make index than to walk from page to page and add
[[Category:<some_category>]] and for some articles multiple times.
> I am more of a package manager specialist. I could volunteer to
> document package management (apt, yum, rug, zmd, smart. etc..)
.....
That is how it works, everybody writes what likes the most.
It doesn't hurt if one is expert for the field and good writer, but such
combinations are seldom, and we have to rely on a team work. One writes, and
later others add paragraphs, links, templates and images, clean errors in
spelling and style, rewrite to make it more readable, give comments and ask
questions on corresponding discussion pages.
--
Regards,
Rajko M.
---------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org
For additional commands, e-mail: opensuse-doc+help(a)opensuse.org
On Tuesday 03 October 2006 17:02, Gary Cottreau wrote:
> I took one look at documentation efforts and was overwhelmed and
> disappointed.
>
> You have some good points, but this is not easy for a non technical person.
>
> I would be glad to help; but, I am not going to climb any mountains for
> this. Make it as simple and easy as possible to invite people in and get
> involved
>
> I am not going to learn special formats, use special tools, or any of the
> BS... I have much better things to do with my time.
>
> If there is no system in place that easy enough to use -- that a 14 or 15
> year old could use - I consider this a failure. Especially since this
> effort will be multi-lingual and we should keep this easy so it translates
> to other languages.
>
>
> Team work makes the dream work.
>
> Gary Cottreau
Thanks for comment, Garry.
If you can give few more details, what you looked at, and what seems to be too
complicated, it will help us and the openSUSE guys, that actually can do
something if there is sufficient interest.
--
Regards,
Rajko M.
---------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org
For additional commands, e-mail: opensuse-doc+help(a)opensuse.org
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: opensuse-doc+unsubscribe(a)opensuse.org
For additional commands, e-mail: opensuse-doc+help(a)opensuse.org