Page 1 of 2 12 LastLast
Results 1 to 10 of 15

Thread: Where has official (PDF) documentation gone?

  1. #1
    Join Date
    Jan 2012
    Location
    Russia :: Moscow
    Posts
    45

    Default Where has official (PDF) documentation gone?

    There once was a nice set of openSUSE user manuals in PDF form covering pretty everything, — the main document had near 30 chapters in more than 500 pages, and there were also separate documents focusing on more specific topics. At least I still see something like that for openSUSE 11.0 on Novell site and from 11.3 to 12.2 on doc.opensuse.org, but had no luck finding similar thing for current releases.

    • In YaST package manager there is patterns-openSUSE-books item in Documentation section, but it provides no real content.
    • The main wiki has Documentation portal which says that Official openSUSE documentation is at ActiveDoc.opensuse.org.
    • Same thing is stated on Official documentation sandbox page of the main wiki.
    • That ActiveDoc server blindly redirects to doc.opensuse.org.
    • Surprisingly, doc.opensuse.org's front page also suggests the ActiveDoc site — not only in the page preface, but in each and every particular link regarding openSUSE 13.1 documentation, — thus creating an infinite loop.
    • Trying to access the mentioned URIs from doc.opensuse.org itself gives nothing but a 404 Not Found error.

    So, am I missing something obvious? Where that openSUSE Reference can be found now?

  2. #2

    Default Re: Where has official (PDF) documentation gone?

    Quote Originally Posted by SamsonovAnton View Post
    There once was a nice set of openSUSE user manuals in PDF form covering pretty everything, — the main document had near 30 chapters in more than 500 pages, and there were also separate documents focusing on more specific topics. At least I still see something like that for openSUSE 11.0 on Novell site and from 11.3 to 12.2 on doc.opensuse.org, but had no luck finding similar thing for current releases.
    Starting with openSUSE 12.3 we moved the documentation to activedoc.opensuse.org, in a move to allow the community to easily contrbute to the manuals. However, we did not get as much contributions as we expected. Therefore two weeks ago the SUSE documentation team decided to take care of the openSUSE ocumentation again. Since then, openSUSE Leap 42.1 documentation is available on http://doc.opensuse.org/ (and we will publish updated documentation for upcoming Leap releases there, too).

    --
    Frank Sundermeyer
    SUSE Documentation Project Manager
    "Reality is always controlled by the people who are most insane" Dogbert
    "Reality is always controlled by the people who are most insane" Dogbert

  3. #3
    Join Date
    Jun 2008
    Location
    San Diego, Ca, USA
    Posts
    10,942
    Blog Entries
    2

    Default Re: Where has official (PDF) documentation gone?

    Quote Originally Posted by fsundermeyer View Post
    Starting with openSUSE 12.3 we moved the documentation to activedoc.opensuse.org, in a move to allow the community to easily contrbute to the manuals. However, we did not get as much contributions as we expected. Therefore two weeks ago the SUSE documentation team decided to take care of the openSUSE ocumentation again. Since then, openSUSE Leap 42.1 documentation is available on http://doc.opensuse.org/ (and we will publish updated documentation for upcoming Leap releases there, too).

    --
    Frank Sundermeyer
    SUSE Documentation Project Manager
    "Reality is always controlled by the people who are most insane" Dogbert
    Hmmmm....
    I've looked over the Virtualization "Books" because it's something I know pretty well and IMO it's only suitable for someone's early baby steps when they are just getting started.
    The Virtualization content is rife with half-truths and definitions on every page and on some pages although won't get a beginner in trouble immediately are very, very wrong about architecture and definitions so is putting a lot of wrong information into the reader which stunts further learning.

    At least regarding virtualization, for now I'd recommend a User simply search the posts in the Virtualization forum for how to do things, and there are questions about how things work, are architected or choices, just ask in that Forum.

    Also, I highly recommend the SUSE KVM documentation in general, it's very good and free from any errors AFAIK. Although written for SLES 11 SP4, it's all applicable to any other SLES and LEAP.
    https://www.suse.com/documentation/s.../book_kvm.html

    I assume the corresponding SLES Xen documentation should be just as good
    https://www.suse.com/documentation/s.../book_xen.html

    I haven't evaluated SLES LXC documentation so can't recommend or not
    https://www.suse.com/documentation/s..._lxcquick.html

    And, I haven't seen anything other than my own personal writings about using Docker...
    https://en.opensuse.org/User:Tsu2#Docker

    I see some interesting stuff skimming the other "Books" but the Virtualization Book needs re-working...

    TSU
    Beginner Wiki Quickstart - https://en.opensuse.org/User:Tsu2/Quickstart_Wiki
    Solved a problem recently? Create a wiki page for future personal reference!
    Learn something new?
    Attended a computing event?
    Post and Share!

  4. #4
    Join Date
    Jan 2012
    Location
    Russia :: Moscow
    Posts
    45

    Default Re: Where has official (PDF) documentation gone?

    Quote Originally Posted by fsundermeyer View Post
    We did not get as much contributions from the community as we expected. Therefore two weeks ago the SUSE documentation team decided to take care of the openSUSE ocumentation again.
    In my not so humble opinion, documents of such quality should better be written by as few people as possible, — ideally by a single person per knowledge domain. Wiki-style of editing is more suited for isolated articles, FAQs and how-tos, not for books. So your recent decision was entirely right, thank you so much — that is exactly that I was looking for.


    Quote Originally Posted by tsu2 View Post
    Virtualization "Books" is only suitable for someone's early baby steps when they are just getting started. For now I'd recommend a User simply search the posts in the Virtualization forum.
    While I cannot judge on current content's truthfulness and completeness (my own fear is that it may not be up-to-date, especially regarding Xen), but I am very confident that such form of documentation is the very best for beginners — not only explaining basics in a highly systematic way, but also teaching how to do things in ${distroname} way. In contrast, learning from forum posts and "repeat after me" how-tos tends to be shallow and confusing, making to get accustomed to bad practices. That is why books are so important, and if you see errors there, please, inform the authors so they could improve the text, or even volunteer to become an author yourself.

  5. #5
    Join Date
    Feb 2010
    Location
    Germany
    Posts
    2,478

    Default Re: Where has official (PDF) documentation gone?

    Quote Originally Posted by SamsonovAnton View Post
    In my not so humble opinion, documents of such quality should better be written by as few people as possible, — ideally by a single person per knowledge domain.
    As an absolutely non-humble software tester, my view is that because "human beings produce errors" (only robots can produce error-free products) all text (including program code) must be reviewed and inspected and (ideally) tested and written by a group of people who have subject insight . . .
    Considering the issues of consistent style and uniform appearance, simply allowing one single human being to write text blocks does not automatically guarantee consistent style and uniform appearance; the human brain ensures that we all tend to deviate during writing and therefore each individual human being tends to produce inconsistent text styles and non-uniform appearance.
    Yes, yes, strict text-frame based text production tools can help to guide authors to produce text with a consistent style and a uniform appearance but, expect an initial resistance from the authors when they are first confronted with these tools . . .

    Quote Originally Posted by SamsonovAnton View Post
    Wiki-style of editing is more suited for isolated articles, FAQs and how-tos, not for books.
    Yes, yes, but, in an open-source world the Wiki method is extremely useful for conducting reviews of submitted text and for gathering the material needed for the production of more "formal" documentation . . .

    Quote Originally Posted by SamsonovAnton View Post
    While I cannot judge on current content's truthfulness and completeness (my own fear is that it may not be up-to-date, especially regarding Xen), but I am very confident that such form of documentation is the very best for beginners — not only explaining basics in a highly systematic way, but also teaching how to do things in ${distroname} way. In contrast, learning from forum posts and "repeat after me" how-tos tends to be shallow and confusing, making to get accustomed to bad practices. That is why books are so important, and if you see errors there, please, inform the authors so they could improve the text, or even volunteer to become an author yourself.
    Agreed; good documentation is needed at all levels of any given product:
    • short, concise and precise guides for the "1st contact" case;
    • moderately detailed documentation for change planning and testing;
    • detailed documentation for the system architects, designers and developers.

    Yes, yes, I know: "Code is fact, documentation is fiction!"

  6. #6
    Join Date
    Jun 2008
    Location
    San Diego, Ca, USA
    Posts
    10,942
    Blog Entries
    2

    Default Re: Where has official (PDF) documentation gone?

    After having examined a number of other Guides,
    Most of what I read looks pretty good.
    Some stuff I knew, plenty of stuff I didn't and generally all easily understood.

    Here's hoping that the Virtualization guide is brought up to the level of the others, as I described earlier although I don't see specific described methods and steps that are so inaccurate so as to cause harm, a very large (even majority) of the content is very weak on technological concepts, so much that if a reader relies on the information there would be plenty of un-learning to do and might not be able to progress beyond simple introduction to setting up.

    IMO,
    TSU
    Beginner Wiki Quickstart - https://en.opensuse.org/User:Tsu2/Quickstart_Wiki
    Solved a problem recently? Create a wiki page for future personal reference!
    Learn something new?
    Attended a computing event?
    Post and Share!

  7. #7

    Default Re: Where has official (PDF) documentation gone?

    Quote Originally Posted by tsu2 View Post
    Hmmmm....
    I've looked over the Virtualization "Books" because it's something I know pretty well and IMO it's only suitable for someone's early baby steps when they are just getting started.
    The Virtualization content is rife with half-truths and definitions on every page and on some pages although won't get a beginner in trouble immediately are very, very wrong about architecture and definitions so is putting a lot of wrong information into the reader which stunts further learning.
    Being one of the three authors of the Virtualization Guide I think this general statement is neither true nor fair (especially in the light of what you say below, see my comments on that). Sure, the guide is probably not perfect, nor error-free. But saying it is "rife with half-truths and definitions on every page" without giving any proof of it is not helpful at all.

    Feedback (and that includes negative one) is always welcome, but if it does not include the slightest hint on what needs to be changed, there is little we can do with it. If we receive constructive criticism we may not react immediately, but you can be sure that it is not forgotten and will be considered in future editions of our manuals.

    At this point I need to mention that TSU2 offered help in a private comment, which is much appreciated!

    Quote Originally Posted by tsu2 View Post
    Also, I highly recommend the SUSE KVM documentation in general, it's very good and free from any errors AFAIK. Although written for SLES 11 SP4, it's all applicable to any other SLES and LEAP.
    https://www.suse.com/documentation/s.../book_kvm.html

    I assume the corresponding SLES Xen documentation should be just as good
    https://www.suse.com/documentation/s.../book_xen.html

    I haven't evaluated SLES LXC documentation so can't recommend or not
    https://www.suse.com/documentation/s..._lxcquick.html
    Funny thing is, that the Virtualization Guide is the result of a merge of these three guides. Since all can be managed using libvirt and tools we decided to merge these separate guides into a single virtualization guide. The KVM and libvirt part (the former SUSE KVM manual) remained almost unchanged (apart from significant additions to the libvirt chapter "Configuring VMs"), parts of the XEN and LXC guide have been changed to fit the new structure.

    Quote Originally Posted by tsu2 View Post
    And, I haven't seen anything other than my own personal writings about using Docker...
    https://en.opensuse.org/User:Tsu2#Docker
    Absolutely true - Docker is currently missing. We have a Quickstart for SLE 12 SP1 which, in large parts should also apply to openSUSE at https://www.suse.com/documentation/s...ckerquick.html . I will have a look into it and will add it to the Virtualization Guide for Leap 42.2.

    --
    Frank Sundermeyer
    SUSE Documentation Project Manager
    "Reality is always controlled by the people who are most insane" Dogbert

  8. #8
    Join Date
    Jun 2008
    Location
    San Diego, Ca, USA
    Posts
    10,942
    Blog Entries
    2

    Default Re: Where has official (PDF) documentation gone?

    Quote Originally Posted by fsundermeyer View Post
    Being one of the three authors of the Virtualization Guide I think this general statement is neither true nor fair (especially in the light of what you say below, see my comments on that). Sure, the guide is probably not perfect, nor error-free. But saying it is "rife with half-truths and definitions on every page" without giving any proof of it is not helpful at all.

    Feedback (and that includes negative one) is always welcome, but if it does not include the slightest hint on what needs to be changed, there is little we can do with it. If we receive constructive criticism we may not react immediately, but you can be sure that it is not forgotten and will be considered in future editions of our manuals.

    <snip>

    --
    Frank Sundermeyer
    SUSE Documentation Project Manager
    OK, here it comes...

    After thinking about your documentation more,
    I'm beginning to believe that the actual problem isn't that most of the written information is incorrect (It still is), but that it's because the Author(s) are likely Xen users and don't really use other virtualization that much.


    Xen is a completely different beast, in its own category (often referred to as Gen1 virtualization which is <not> less capable than Gen2 which is the rest of all virtualization including KVM, VMware, VBox, Hyper-V, Parallels and more). Besides its own unique foundation architecture, for whatever reason Xen uses same terminology as everyone else to describe completely different things. So, if you intend to apply your Xen definitions and understanding to anything outside of Xen... Well, good luck. You won't go too far before things will become very wrong when you discuss with and about other virtualization.


    I admit that I personally view Xen more as something interesting from afar, because I haven't found a need to deeply use it, but I use many others including KVM, VMware, VBox and Hyper-V and so I live in a world that all the virtualization I use do speak more or less the same language and are built and define things similarly.


    That said,
    The following is a short list (not intended to be complete) on where existing documentation is wrong, and since the list is long did not post before. For the Xen user, these errors might not be recognized but the errors I describe do not describe Xen specifically, they are supposed to describe other virtualization or virtualization in general (most of the world).


    When necessary, I am double-checking Xen architecture referencing the following Xen Project page
    http://wiki.xen.org/wiki/Xen_Project_Software_Overview


    1.4 Full Virtualization is not described accurately, and actually has little to do with underlying hardware assist which is often disabled or not used which <enables> full emulation of non-x86 architectures when running on an x86 CPU. By its very name "paravirtualization" means that virtualization is based on, and is direct access to the CPU. Yes, Xen defines everything differently. "Full Emulation" for the rest of the world is basically non-hardware software emulation but somehow Xen seems to want to say that theirs is hardware based and Xen defines paravirtualization as not using CPU extensions. Xen wants to walk its own walk, but it's not the "world definition"


    1.5 I/O virtualization is generally considered separate from the CPU and was created to make this distinction during the evolution of virtualization which was historically Gen1 (CPU and memory only), Gen2 (CPU and memory, plus device I/O), more or less. there is plenty of disagreement exactly where the distinctions and generations are defined and some will define Gen2.5 to further distinguish between different types of I/O devices and now, moving forward even a Gen3. These evolutionary "Gen" labels are different than the "Gen" labels mentioned above that differentiate Xen from the rest of the world.


    3.1 Saying KVM is a "full virtualization solution" is not accurate if you define full virtualization as full emulation. By default, KVM is implemented as paravirtualization, and only optionally can implement full emulation(virtualization) since the integration of QEMU. If you might mean that a "full solution" means that KVM supports a multitude of scenarios generally, then this word choice is confusing.


    4.0 Saying that Linux Containers in any way virtualizes anything including the kernel has to be technically false, assuming the common definition of virtualization. Container processes aren't run as virtualized representations of something else, they are no different than any other running process. Linux Containers are isolation, pure and simple with <no> virtualization <except> in <some> implementations networking objects (LXC but AFAIK no other Linux Containers implementation including docker and systemd-nspawn). Also, it should be noted that this documentation only defines "Linux Containers" as LXC and ignores all other implementations of linux containers.


    4.1 I think you can remove the "nearly" word when describing performance.
    controlling network interfaces through cgroups? I'd have to check up on that... That's a bold statement I haven't seen before, so I find suspicious. Depending on what you mean by security, using cgroups and process labels are significant security measures, I don't know if non-security folk can distinguish or understand properly what was stated here.


    5.0 In general, nothing wrong in the section. But, does not describe the scope of what libvirt can do, it can be used to manage at least a dozen or so different virtualization technologies, not just the three mentioned. Yes, SUSE/openSUSE only implements the three. If you install OpenStack on SUSE/openSUSE, you'll also be using libvirt to support docker. BTW - considering how important docker has become to Linux and computing in general (it's one of the top 3 topics for 3 years running at the Linux conferences I go to), it's likely a serious omission if you're describing Linux Containers. For now, unless you're running OpenStack, openSUSE is providing a separate, non-libvirt management tool.


    7.1 Why should paravirtualization support be any different for any Linux Guest distros? For that matter, why should Windows not be supported by paravirtualization, since the Windows kernel will have direct access to the CPU? Plenty of questionable things, this whole table should be re-written or thrown out, it's based either on outdated info or has been mis-interpreted in its new incarnation. Or, again this section might have been written "The World according to Xen" which would become erroneous when applied to other virtualization.


    7.1.1 As I alluded before, I highly recommend using the term "device drivers" instead of just "drivers" to be more exact, otherwise the info is only half correct. This is because this applies only to getting data in and out of the virtual machine and does not apply to any other types of drivers.


    7.3 How about that. Description is accurate although I don't know if the author really understood the accuracy of what was written. Should use the word "paravirtualization" to neatly tie up the relationship of hardware CPU extensions and what paravirtualization is to make this fully clear.


    7.4 Needs to make clear this section applies <only> to Xen which is a completely different architecture than any other (often referred to in its own way as Gen1 virtualization). Every other paravirtualization technology I know of uses the "other" fundamental architecture (often referred to as Gen2) (The Gen number is not necessarily an indication Gen2 is any more advanced, it's just different). Besides not specifying Xen in the title of this section, at least the HTML docs place this on the same page as the previous KVM documentation.


    13.0 I don't think there is understanding of the Linux Bridge Device and its relationship with virtual networks. The documentation seems to simply assume that a virtual network will magically work with only its XML file definition, but that's not true. The reader should be introduced to the Linux Bridge Device (possibly with existing, maybe expanded description of brctl) and that it is the fundamental device upon which <all> network connections of all types are made, not just the physically bridging configuration described.




    I'm sure that there is more that has to be evaluated, but that is as much as I can skim over for now... Again, I'm pretty certain that everything I've described can be more accurately found in the other references I provided earlier


    TSU
    Beginner Wiki Quickstart - https://en.opensuse.org/User:Tsu2/Quickstart_Wiki
    Solved a problem recently? Create a wiki page for future personal reference!
    Learn something new?
    Attended a computing event?
    Post and Share!

  9. #9
    Join Date
    Jun 2008
    Location
    San Diego, Ca, USA
    Posts
    10,942
    Blog Entries
    2

    Default Re: Where has official (PDF) documentation gone?

    A tiny update to my previous post when I mentioned how surprising to me that network interfaces would be controlled by cgroups...

    Unless a new reference can be found, the web search hits I'm getting that I consider authoritative are describing network interfaces as controlled by namespaces and should be included in the cgroup of the container.

    This is totally logical, and is not the same as setting up some cgroup specifically for a network interface(s).

    I may still be surprised with a new reference somewhere...
    TSU
    Beginner Wiki Quickstart - https://en.opensuse.org/User:Tsu2/Quickstart_Wiki
    Solved a problem recently? Create a wiki page for future personal reference!
    Learn something new?
    Attended a computing event?
    Post and Share!

  10. #10
    Join Date
    Jun 2008
    Location
    San Diego, Ca, USA
    Posts
    10,942
    Blog Entries
    2

    Default Re: Where has official (PDF) documentation gone?

    Boy, these errors and omissions keep dribbling through my mind even after my previous skim this AM...

    Another what I consider significant error/omission is that the existing documentation leads the reader to believe that libvirt is a must-use with KVM and suggests that virsh is the only way to manage KVM from the command line.

    Of course, it's also possible to use the "kvm" commands if the User wishes, and might be a significant option if libvirt somehow wasn't functional.

    Again, IIRC this is all available in the SLES KVM documentation I referenced...

    TSU
    Beginner Wiki Quickstart - https://en.opensuse.org/User:Tsu2/Quickstart_Wiki
    Solved a problem recently? Create a wiki page for future personal reference!
    Learn something new?
    Attended a computing event?
    Post and Share!

Page 1 of 2 12 LastLast

Tags for this Thread

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •