All my articles in LfL updated to match SUSE Documentation Style Guide

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

All my articles in LfL updated to match SUSE Documentation Style Guide

Alexey Eromenko
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"
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: All my articles in LfL updated to match SUSE Documentation Style Guide

Alexey Eromenko
On 1/29/07, Alexey Eremenko <[hidden email]> 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?

-Alexey Eremenko "Technologov"
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: All my articles in LfL updated to match SUSE Documentation Style Guide

Rebecca Walter
On Tuesday 30 January 2007 18:16, Alexey Eremenko wrote:
> On 1/29/07, Alexey Eremenko <[hidden email]> wrote:
> > Hi susers !
> >
> > Good news:
> > All my articles in LfL updated to match SUSE Documentation Style
> > Guide. (announced earlier today by Rebecca Walter)

Actually, the style guide was already available to LfL, it just wasn't
released as open source yet.

> So what do you think?

I haven't had time to look yet, but I will try to find time.
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: All my articles in LfL updated to match SUSE Documentation Style Guide

Thomas Schraitle-2
In reply to this post by Alexey Eromenko
Hi Alexey,

On Dienstag, 30. Januar 2007, Alexey Eremenko wrote:

> On 1/29/07, Alexey Eremenko <[hidden email]> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: All my articles in LfL updated to match SUSE Documentation Style Guide

Alexey Eromenko
On 1/31/07, Thomas Schraitle <[hidden email]> wrote:

> Hi Alexey,
>
> On Dienstag, 30. Januar 2007, Alexey Eremenko wrote:
> > On 1/29/07, Alexey Eremenko <[hidden email]> 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?

> * 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.

This is does not produce any warnings during "compile" time.

In addition, there is no "quotations" section in the SUSE docs style guide.
I think we need to add one.

> * 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 will check this soon. I don't really understand it's concepts from
your short description.

>
>
> I have concentrated more on technical and structural issues. Probably
> Rebecca will answer the styleguide part.
>
> Keep up the good work! :-)

Thanks.

-Alexey Eremenko. 1.2.2007.
N�����r��y隊Z)z{.��hs맲��r��z�^�ˬz����uح��ڕ�&��ݱ隊Z)z{.��hs�^��)z{.��+�
Reply | Threaded
Open this post in threaded view
|

Re: Re: All my articles in LfL updated to match SUSE Documentation Style Guide

Rebecca Walter

> > * 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.
>
> This is does not produce any warnings during "compile" time.
>
> In addition, there is no "quotations" section in the SUSE docs style guide.
> I think we need to add one.

It isn't covered in the markup section?  If not, we should definitely fix
this.  I will look into it.  Thanks for the feedback!
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]