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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
