openSUSE Documentation

Download

doc@lists.opensuse.org

September 2006

6 participants
1 discussions

[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