Re: Proposed plan for the Virtualization Getting Started Guide

Dayle Parker <dayleparker@xxxxxxxxxx> · Wed, 18 Mar 2015 15:22:07 +1000



    Hi Sandra,

      
      Thanks for the feedback! A bit of background and links below...

      
      On 03/18/2015 06:31 AM, Sandra McCann wrote:

    
      Thanks Dayle!
        

        I took a look at your RHEL quickstart and the flow is quite
          similar to what I'm proposing.  I had a few comments:
        

         - yum install - does RHEL support yum groupinstall? That's
          what I was going to document instead of the individual
          installs.  I have a small section after that to describe what
          some of the packages do (for the curious newbie :-)
        

    Yes, RHEL does support yum groupinstall - that might indeed be
    simpler. Here's the RHEL virt package groups, in case it helps. I'm
    not sure if they're the same in Fedora: 

    
https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Deployment_and_Administration_Guide/sect-Installing_the_virtualization_packages-Installing_virtualization_packages_on_an_existing_Red_Hat_Enterprise_Linux_system.html

    
    Great idea on providing a little bit of info on those packages for
    the more curious :)

    
         - screencaps - I debated this one and was leaning toward
          only having one or two for virt-manager. Most of the steps are
          obvious when you look at the virt-manager gui, so I thought I
          could get away with less images to create/maintain.  That
          said, your approach makes it very obvious what screen the user
          should be on, so now I'm waffling on which approach to take.
      
    
    Agreed, fewer screenshots is always better from a maintenance
    perspective. I wasn't sure either how many to include, but went for
    the whole set of them, just to be extra clear -- also it's what we
    had in the Virt Deployment and Admin Guide. The "New VM" wizard
    screenshots probably aren't necessary, they're more like an
    assurance for the user that they're in the right spot.

    
         - other options to spin up a VM - I mention some of the
          other options in a list, just so the newbie user is aware. I
          figure only virt-manager and boxes will actually be covered in
          detail, and the rest would be in the admin/deploy guide.
        

    Nice. Yeah, originally I planned on including some basic commands,
    but I decided against it for the Getting Started Guide so as to not
    confuse brand new users with too many options.

    
         - boxes - I'm guessing this is only in Fedora, not RHEL? 
          Anyway, I'm leaning toward having boxes as the first procedure
          to cover, since it's installed by default in Fedora
          workstation, where the newbie user is.  Then a separate
          chapter for virt-manager.
      
    
    That makes sense. Boxes is in RHEL actually, but didn't seem like a
    feature an enterprise user would use much, so we opted for a short
    Boxes description in the Getting Started Guide, and a chapter in the
    VDAG (below). Is Boxes used extensively by Fedora users?

    
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html-single/Virtualization_Getting_Started_Guide/index.html#sect-Virtualization_Getting_Started-Tools-Boxes

    
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Deployment_and_Administration_Guide/sect-Graphic_User_Interface_tools_for_guest_virtual_machine_management-GNOME_Boxes.html

    
    Hope that helps a bit. :)

    Cheers,

    Dayle

    
        Thanks,
        Sandra
      
      
        On Mon, Mar 16, 2015 at 10:16 PM, Dayle
          Parker <dayleparker@xxxxxxxxxx>
          wrote:

          
              Hey Sandra,

                
                Thanks for initiating this! I help maintain this guide
                for RHEL and have sadly been too busy lately to get very
                involved on the Fedora side of things. :(

                
                I've been also looking at whether this book has the
                right user in mind for RHEL, and I think currently it's
                aimed at too many types of users -- I agree, the
                novice/GUI focus sounds best. I think some of this guide
                gets pretty technical and detailed in parts, and is
                probably not needed for a novice user.

                
                I've actually added a quick start chapter to the end of
                the guide [1] for RHEL7, so if you want to use any of it
                (the content is under the http://creativecommons.org/licenses/by-sa/3.0/
                license), go for it. (Or if you have any feedback on
                that chapter as a novice, feel free to share).

                
                Also, let me know if you need any help with the project
                -- I really appreciate you taking it on, and I'm happy
                to contribute in little bits if I can!

                
                Cheers,

                Dayle

                
                [1]
                https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Getting_Started_Guide/chap-Virtualization_Getting_Started-Quickstart.html
                
                  
                    On 03/17/2015 11:03 AM, Glen Rundblom wrote:

                  
                   I agree with the plan, and I
                    am happy that Sandra proposed this direction. I have
                    been thinking of how to word my Boxes guide: is this
                    a how-to manual, or just just technical
                    instructions. For me: I learn more from how-to
                    manuals and branch into technical details as I need
                    them. Also, working with the Novice in mind makes me
                    think of the "what if the person does not see..." or
                    "what if they encounter that" and try to solve
                    issues they may encounter as they try to do the
                    task, but may not have the ability to troubleshoot
                    an issue that just happened during the process. 

                    
                    Also, writing for Novices/How-to is more forgiving
                    of first and second person voicing, which I have a
                    tendency to do. 

                    
                    So I have been working with the mindset of a how-to
                    manual for someone beginning with the application,
                    because I am learning the application, publican,
                    docbook, git, mailing lists, and Linux all
                    together!)

                    
                    I have this conception that the more friendly and
                    built for novices something is, the more solid and
                    polished it seems. I am more then willing to put
                    more time and work to make to do that. 

                    
                    So, thank you Sandra!

                    
                    -Glen

                    
                    On 03/16/2015 05:51 PM, Pete Travis wrote:

                    
                      On 03/16/2015 02:28 PM, Sandra McCann wrote:

                      
                              Hi


                                  folks -
                              

                              We’ve


                                  been batting around ideas for the
                                  virtualization guides for a bit now in
                                  irc, but I’d like to get some more
                                  feedback on the approach we can take.
                              

                              Seems


                                  there are two personas involved. Using
                                  our draft


                                    personas
                                  we have :
                              
                                
                                  Technical


                                      Tony - experienced IT person
                                      virtualizing on servers etc, knows
                                      his stuff and is spinning up VMs
                                      like they’re candy.
                                
                                
                                  Novice


                                      Ned (or Novice Nancy in my case
                                      :-) - Fairly new to
                                      virtualization, and looking to
                                      spin up a VM or two for her own
                                      work.
                                
                              
                              Given


                                  these two personas, I’d like to
                                  suggest that the Virtualization
                                  Getting Started guide be targeted to
                                  Novice Nancy. To do this we would:
                              
                                
                                  Add


                                      an installing virtualization tools
                                      chapter - simple effort to install
                                      the virtualization group package
                                      and bring up virt-manager.
                                      (smccann)
                                
                                
                                  Add
                                        an ‘Creating Guests with
                                        Virt-Manager chapter - copying
                                        from here. (smccann)
                                
                                
                                  Adding


                                      a ‘Creating Guests with Boxes
                                      chapter (grundblom)
                                
                                
                                  Make


                                      minor edits as needed to remove
                                      Fedora 19 references and any
                                      references (if present) to a
                                      larger set of virtualization
                                      guides that may not be available
                                      as F21 guides yet.
                                
                              
                              I
                                  also had one question - 
                              
                                
                                  not
                                        sure what to do about the list
                                        of emulated devices - is it
                                        accurate? http://docs.fedoraproject.org/en-US/Fedora/19/html/Virtualization_Getting_Started_Guide/sec-virtualized-hardware-devices.html
                                
                              
                              Anyway,


                                  I’d like to get the getting started
                                  done and committed before considering
                                  the Admin and Deploy guide
                                  (because..ahem.. I AM Novice Nancy
                                  here and it will take longer for me to
                                  parse that guide).
                              

                              Thoughts?
                              Sandra
                              

                      This seems like a solid plan to me.  There's a lot
                      of content in the guide now that's reads strictly
                      as a launch point for the larger guides, so
                      something more like purging paragraphs might be
                      more appropriate than simply removing references. 
                      You have a good idea of where you want to go with
                      it; I only make that point to ensure you don't
                      feel obligated to keep the existing content and
                      write around it.

                      
                      The hardware list is accurate, but not complete. 
                      You might want to focus on a few specific pieces
                      of hardware instead of listing and explaining all
                      possible options though, ie:

                      
                          This is how you add a network device.  This
                      virtio option might need these extra drivers on a
                      windows guest.  

                      
                          This is how you add a virtual block device.
                      This virtio option might need these extra drivers
                      on a windows guest. ( depending on how deep you
                      want to go, you could cover switching out a
                      windows installation iso for the virtio driver iso
                      so it can see virtio storage, then switching
                      back.  There's a definite performance improvement
                      in virtio over SATA emulation, but the setup is
                      going to add a page or two to your instructions) 

                      
                          This is how you provide an ISO to the guest.

                      
                          This is how you share part of the host
                      filesystem with a linux guest

                      
                          These are all spice related devices.  If you
                      choose spice ( the default ) you get them
                      automatically, here is what they do.

                      
                      Things like memory, CPU, input devices are set up
                      automatically, or during initial creation.  IMO my
                      the time you have documented the device types that
                      might need some explanation, the user is familiar
                      with the device management screen and knows where
                      to go, they don't need much or any explanation.

                      
                      Your plan seems GUI focused; I like that.  It
                      makes for a much easier read for new users when it
                      doesn't look like you need to learn a bunch of
                      scary programming to make it work :)  We can put
                      cli stuff somewhere else.

                      
                      -- 
-- Pete Travis
 - Fedora Docs Project Leadt
 - 'randomuser' on freenode
 - immanetize@xxxxxxxxxxxxxxxxx
                      

                  -- 
Dayle Parker
Senior Technical Writer
Red Hat Asia Pacific - Brisbane, Australia
dayleparker@xxxxxxxxxx 
                
          
    -- 
Dayle Parker
Senior Technical Writer
Platform Virtualization Docs Lead

Red Hat Asia Pacific - Brisbane, Australia
dayleparker@xxxxxxxxxx | irc: dayle 
  

-- 
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs