Proposed plan for the Virtualization Getting Started Guide

Tue Mar 17 02:16:23 UTC 2015

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 
>>> <https://fedoraproject.org/wiki/Docs_Project_Focus#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
>>>     <http://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/Virtualization_Deployment_and_Administration_Guide/chap-Virtualization_Host_Configuration_and_Guest_Installation_Guide-Guest_Installation_Virt_Manager-Creating_guests_with_virt_manager.html>.
>>>     (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 at fedoraproject.org
>>
>>
>
>
>

-- 
Dayle Parker
Senior Technical Writer
Red Hat Asia Pacific - Brisbane, Australia
dayleparker at redhat.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20150317/70f43317/attachment.html>