October 2006 - openSUSE Documentation - openSUSE Mailing Lists

[opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
by Rajko M 12 Oct '06

12 Oct '06

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

9 43

[opensuse-doc] [ANN] Susedoc XML Build Environment
by Thomas Schraitle 12 Oct '06

12 Oct '06

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

3 6

Re: [opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
by Rajko M 04 Oct '06

04 Oct '06

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

1 0

Re: [opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
by Rajko M 04 Oct '06

04 Oct '06

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

1 0

Re: [opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
by Rajko M 01 Oct '06

01 Oct '06

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

1 0