Hi,
On Saturday 06 January 2007 00:14, Alexey Eremenko wrote:
>
> > > I commited first series of How-Tos to LfL ! ! ! !
>
> I would be happy if someone could look at them and tell me how are they!
That's a good start! I had a quick look at the XML code, unfortunatly I
haven't had the time to look at the text.
You can improve your code by changing it slightly. I would like to suggest
to use the following (used howto-swapfile.xml to describe it):
1. Use orderedlist instead of manually insert your numbers in a para. This
gives you the advantage of automatically generated numbers and it
doesn't break if you move, add ore delete one. Instead of:
<para>1. You want to frequently change the swap-size; or</para>
<para>2. Just save you from extra entries in partition table;...</para>
<!-- ... --->
Replace it with:
<orderedlist>
<listitem>
<para>You want to frequently change the swap-size; or</para>
</listitem>
<listitem>
<para>Just save you from extra entries in partition table;...</para>
</listitem>
<!-- ... --->
</orderedlist>
2. Use element screen when a user sees or might see text on a computer
screen. Instead of:
<para>
# dd if=/dev/zero of=swapfile.img bs=$[1024*1024*256] count=1
</para>
Replace it with (in one line):
<screen># dd if=/dev/zero of=swapfile.img bs=$[1024*1024*256]
count=1</screen>
3. Describe commands in your paragraph with the command element:
<para>Understanding the command "dd" ... </para>
Replace it with:
<para>Understanding the command <command>dd</command> ... </para>
4. Use xrefs instead of hardcoded text. Like the orderedlist, this
has the advantage it doesn't break if you move, delete or add
steps. You have to add an id attribute in your listitem, like this:
<listitem id="li.swap.swapsize">
<para>You want to frequently change the swap-size; or</para>
</listitem>
To use it, use <xref linkend="..."/> and point to your previous
id. Instead of:
<para>Understanding the command "dd" from step 1 ...</para>
You write:
<para>Understanding the command <command>dd</command> from
<xref linkend="li.swap.swapsize"/> ...</para>
Voila!
I think you got the idea. :-) Next time I will have probably more time to
look at your text.
Best wishes,
Tom
--
----------------------------------------------------------------------
SUSE LINUX Products GmbH >o) Documentation Team
Maxfeldstrasse 5 /\\ Technical Editor
90409 Nuernberg, Germany _\_v http://en.opensuse.org/Documentation_Team
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
