On 14.09.2008 15:35, Tom "spot" Callaway wrote:

On Sun, 2008-09-14 at 10:36 +0200, Thorsten Leemhuis wrote:

Yes, I know, enlightenment is designed for small machines and quite
fast
on them. But those things I quoted and other sections in the
description
sound more like advertising than a proper description. Up to a
specific
point that's okay IMHO, but here the packager IMHO shoot way over the

top.

Wow. That is indeed too much information. I'm not sure how we should
"guideline" that, other than something like:

== Descriptions ==
Your package description should contain useful data about the package,
and answer the question "what is this and what does it do?". In general,
the description should not exceed 10 lines or so. Try not to put too
much here, this isn't an epic novel, it's just a package description.
Also, there is no real need to "advertise" the package here, so
statements like "this is the best perl module that has ever been created
by humans", while possibly accurate, are not terribly useful in
answering the question "what is this and what does it do?".


Sounds good. Not sure, but maybe it's possible to write it a bit shorter
to work against the "guidelines grow and grow" trend (¹). Maybe
something like this is enough:


"""
The description should not be exceed round about ten lines of text and
contain useful data about what the packaged software does. The
description should be written from a distance point of view and not
sound like advertising.

"""

I suppose a native English speaker is able to write it more clear in
less words.


CU
knurd

(¹) -- heck, maybe this should not be in the guidelines at all; maybe a
new "best practices" document might be a better place for this and
similar things, as "description not to long, no advertising style" is
obvious to round about 99 percent of our packagers...


--
Fedora-packaging mailing list
Fedora-packaging@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-packaging

On Mon, 2008-09-15 at 13:53 +0200, Thorsten Leemhuis wrote:
> On 14.09.2008 15:35, Tom "spot" Callaway wrote:
> > On Sun, 2008-09-14 at 10:36 +0200, Thorsten Leemhuis wrote:
> >> Yes, I know, enlightenment is designed for small machines and quite
> >> fast
> >> on them. But those things I quoted and other sections in the
> >> description
> >> sound more like advertising than a proper description. Up to a
> >> specific
> >> point that's okay IMHO, but here the packager IMHO shoot way over the
> >> top.
> > Wow. That is indeed too much information. I'm not sure how we should
> > "guideline" that, other than something like:
> >
> > == Descriptions ==
> > Your package description should contain useful data about the package,
> > and answer the question "what is this and what does it do?". In general,
> > the description should not exceed 10 lines or so. Try not to put too
> > much here, this isn't an epic novel, it's just a package description.
> > Also, there is no real need to "advertise" the package here, so
> > statements like "this is the best perl module that has ever been created
> > by humans", while possibly accurate, are not terribly useful in
> > answering the question "what is this and what does it do?".
+1

> Sounds good. Not sure, but maybe it's possible to write it a bit shorter
Agreed. Shorter would be better.

Futhermore, I'd like to see some words added aiming at use of
non-self-explanatory acronyms/names and redundant wording.

I am getting the creeps when reading descriptions similar to
"Hawaii, the Moscow-daemon for Tokio, a free open-source implemention of
PROZL/RKNR for GNIZL implemented by Dr. J.Doe at IRTX in
Nutbush-City/TX."

Everything in Fedora is supposed to be "open source" ... who implemented
it and where is non-interesting ... Hawaii, Moscow, Tokio etc. don't
tell much to anybody, who aren't already familiar with any of these.

Ralf


--
Fedora-packaging mailing list
Fedora-packaging@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-packaging