Re: [opensuse-doc] Updated article of VirtualBox + openSUSE

8 Mar 2007

      Hi Alexey,

On Mittwoch, 7. März 2007, Alexey Eremenko wrote:
...
I have just updated my article (part of LfL, SUSE documentation) -
that explains step-by-step about configuring VirtualBox on openSUSE
system.
HTTP link:
http://download.yousendit.com/62543C517313426E
The new, updated article also includes information about 2 Hot
Topics: Host Networking and USB. (thanks Pablo!), plus it has
extended database for troubleshooting & tips and a lot of useful
external links.
What do you think of this article?
Thanks for the update! :-)

I have some suggestions, maybe you find it useful:

1. Section "Terminology":
   "...  this is *what* you are trying to emulate."
   use <emphasis>what</emphasis> instead of *what*

2. You used an orderedlis in section "Basic Configuration Procedure".
   That's possible but I would say a procedure fits semantically
   better, because you describe a task here.
   Another issue are the 17 "steps". I would suggest to group them
   into smaller units with substeps. This helps your reader to skim
   through the task and it is much more readable. For example, a
   procedure with substeps looks like this:

   <procedure>
     <step>
      <para>Downloading VirtualBox</para>
      <substeps>
       <step>
        <para>Download VirtualBox from ...</para>
       </step>
       <step>
        <para>Choose ...</para>
       </step>
      </substeps>
     </step>
     <step>
      <para>Installing VirtualBox</para>
      <substeps>
       <step>
        <para>...</para>
       </step>
      </substeps>
      <!-- ... -->
     </step>
     <step>
      <para>Configuring VirtualBox</para>
      <substeps>
       <step>
        <para>...</para>
       </step>
      </substeps>
      <!-- ... -->
     </step>
    </procedure>

2. Step 4 is IMHO too simple. :) You group guimenus into menuchoice
   (which is fine) but acutally some content is not a guimenu 
   at all. I would separate them. For example:

   Setup your user(s) to be part of “vboxusers” group. Start
   YaST and select Security and Users+Group Management.
   Create a new group with ...

   Maybe you can even separate this step into two individual steps?

3. In step 11 a verb (select?) is missing.

4. Step 13 contains a kaskade of guimenus, but without a menuchoice.
   Wrap a menuchoice around them and remove the "->". 

5. Section "Setting up Guest VM Additions":
   You can put your "NOTE: That linux-sources..." into a real
   note like the warning in the same section.

6. Section "Advanced Topic: Networking via Host Bridging":
   ... user “tux”.
   Better use this:
   <systemitem class="username">tux</systemitem>
   (Search in your article if there are other occurances of
    users and replace them with systemitem.)

7. Use a procedure for the orderelist "As we said earlier,..." 

8. Section "Advanced Topic: HOWTO USB + openSUSE 10.2 + 
   VirtualBox 1.3.6":
   You used kind of subsections ("Slower bootup of VM", 
   "Preconditions") which I would transform into a sect3.
   Another point is: I would move the acknowledgments into
   your respective "Thanks" section.

9. Section "Troubleshooting and Tips": ... press Right “Ctrl+F”
   Better use keycap and keycombo. :)

10. Section "Thanks", Article first released on ...
   If you want a revision history for your article, there is the
   tag revhistory for this purpose. Insert it inside your
   sect1info. For more information, see
   http://www.docbook.org/tdg/en/html/revhistory.html

Best wishes,
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@opensuse.org
For additional commands, e-mail: opensuse-doc+help@opensuse.org