Hi Alexey,
On Dienstag, 30. Januar 2007, Alexey Eremenko wrote:
> On 1/29/07, Alexey Eremenko <[EMAIL PROTECTED]> wrote:
> > Hi susers !
> >
> > Good news:
> > All my articles in LfL updated to match SUSE Documentation Style
> > Guide. (announced earlier today by Rebecca Walter)
> >
> > It took me just a few hours of work to read and accomplished
> > those recommendations.
> > I already commited the updated versions, so you judge the
> > "successfullity" of my undertaking.
> >
> > -Alexey Eremenko "Technologov"
>
> So what do you think?
Thanks for all your good articles, Alexey! I was busy in the last days
so I hadn't had the time to look at your files as I wished.
I have only some small suggestions, others may have additional
comments (hope it doesn't sound to harsh or picky):
* Try to use more procedures, if applicable. Procedures tell your
readers what they have to do actually. Be precise as possible. Start
with a verb. For example, in file "lg3d.xml" you have this step:
1. First, you must get LG3D from their site:
https://lg3d.dev.java.net/lg3d-getting-started.html as it is not
included with openSUSE. Choose "binary mega-bundle" for Linux,
x86. It includes Java6, Java3D and LG3D and weigths at about
150 MB
What do you think about this?
1. Download the LG3D from
https://lg3d.dev.java.net/lg3d-getting-started.html. It is not
included in openSUSE.
2. Choose "binary mega-bundle" for Linux, x86. It includes Java6,
Java3D and LG3D (around 150 MB).
* Omit quotes, if possible. I mean, the directly inserted one,
like "this". From a typographical point of view this looks ugly and
it depends on the language. Use always <quote>this</quote>. You get
the advantage it is fully localizable. In English you get “this”, in
German „this“ etc. depending on the language.
* Think about quotes again. Maybe the element command is better
suited? :) For example, if you talk about the "dd" command, better
insert in your XML code <command>dd</command>.
* What do you think about lists in the "For more information" section?
Depending on whether you want to explain the links or just want to
list them, you can use variablelist or itemizedlist. An example for
the first may looks like this:
<variablelist>
<varlistentry>
<term><ulink url="http://www.example.com"/></term>
<listitem>
<para>Insert your description here...</para>
</listitem>
</varlistentry
<!-- Insert more entries here -->
</variablelist>
An example for the second one looks like this:
<itemizedlist>
<listitem>
<para><ulink url="http://www.example.com"/></para>
</listitem>
<!-- Insert more entries here -->
</itemizedlist>
* Yesterday I created an RPM package of xmlformat. This is a Perl or
Ruby script that can be applied to any XML files to get consistent
indentation. Few minutes ago I commited a configuration file for
xmlformat in common/config. You can run it with:
$ .../lessons4lizards/trunk/books/en> xmlformat.pl \
--config-file ../../common/config/docbook-xmlformat.conf \
xml/howto-swapfile.xml
The above command prints an indented version of your XML file to
standard out. If you want to replace it, add the additional
option --in-place. Search for help with "--help".
With xmlformat XML files are more legible and it's more consistent.
What do you think about this? :)
I have concentrated more on technical and structural issues. Probably
Rebecca will answer the styleguide part.
Keep up the good work! :-)
Hope this helps,
Tom
----------
[1]
https://forgesvn1.novell.com/svn/lfl/trunk/common/xml/topic-template.xml
[2]
http://software.opensuse.org/download/home:/thomas-schraitle/openSUSE_10.2/
--
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]
