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