Re: Review for the english description of a new package
Joseph Herlant wrote:
> I am currently creating a new package and as I'm not English native, I
> would like someone to review the English description of my package.
Sure, no trouble.
> Package: gnome-shell-pomodoro
[...]
> Description: GNOME Shell extension manages time using Pomodoro technique
I see what you mean, but tidying up the grammar:
Description: GNOME Shell extension for managing time using the Pomodoro technique
Except that that's a bit long. It seems to me you could get away with
just:
Description: GNOME Shell time-management extension
...and leave the explanation of the name for the long description.
Oh, and then I see that the upstream website says it's no longer a
GNOME Shell extension (whatever that is exactly), it's an app. Does
that mean a generic GTK application, a GNOME-specific app, or a widget
that still works via the GNOME Shell? I'm going to guess you just
need to search-and-replace s/extension/app/ throughout, not (for
instance) change the package name.
> This GNOME Shell extension helps you to manage time according to Pomodoro
> technique.
Insert article: "the Pomodoro technique". Except that surely it's
either "the Pomodoro Technique" or "the pomodoro technique"? Since
it's not named after the inventor I'll go for the latter.
> .
> Features:
> Countdown timer in the GNOME Shell top panel
> Full screen notifications that can be easily dismissed
> Reminders to nag you about taking a break
If all the following items are part of a list, you'll need to give
them a one-character indent to indicate that they shouldn't get their
whitespace re-wrapped. I would recommend a format like:
Features:
* countdown timer in the GNOME Shell top panel;
* full screen notifications that can be easily dismissed;
* reminders to nag you about taking a break;
Otherwise the content is fine so far.
> Sets your IM (Empathy) status to busy
> Hides any notifications until the start of break
The list has switched from noun phrases to verb phrases, which is
awkward. And these last two make it really hard to standardise in the
direction of nouns... it's easier to do it the other way. And
reshuffling their order might also help:
Features:
* puts a countdown timer in the GNOME Shell top panel;
* nags you with reminders about taking a break;
* uses full screen notifications that can be easily dismissed;
* hides other notifications until the start of the break;
* sets your IM (Empathy) status to "busy".
> .
> What is the Pomodoro technique?
Without a separating empty line this question would be re-wrapped into
the answer, but package descriptions don't conventionally have this
sort of article structure; just drop this line.
The description that follows sounds like faddy nonsense to me (given
that nobody's offering statistics from proper double-blind trials
comparing it with equally obvious alternatives such as a 4×35 minute
cycle), but it's not as if it's claiming to cure cancer, so never
mind.
> The Pomodoro technique is a time and focus management method which improves
> productivity and quality of work. The name comes from a kitchen timer, which
> can be used to keep track of time. In short, you are supposed to focus on work
> for around 25 minutes and then have a well deserved break in which you should
> relax. This cycle repeats once it reaches 4th break – then you should take a
Good English up to here, but it isn't true that it "repeats once it
reaches 4th break". Say:
This cycle repeats, then once it reaches the fourth break you should take a
or maybe Then when this cycle repeats for the fourth time you should take a
> longer break (have a walk or something). It's that simple. It improves your
> focus, physical health and mental agility depending on how you spend your
> breaks and how strictly you follow the routine.
That last sentence seems somewhere between vacuous and tendentious:
obviously taking breaks can often be beneficial, but equally there are
some kinds of mental task where frequent interruptions won't help.
Besides, any time you say "it's that simple" and carry on, you're
undermining yourself!
(ObWhyTheName: it may not be obvious that the technique's inventor was
Italian and had a kitchen timer shaped like a tomato.)
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Source: gnome-shell-pomodoro
Maintainer: Joseph HERLANT <herlantj@gmail.com>
Section: gnome
Priority: extra
Build-Depends: gnome-common, intltool, libglib2.0-dev, debhelper (>= 8.0.0)
Standards-Version: 3.9.5
Homepage: https://github.com/codito/gnome-shell-pomodoro/
Vcs-Browser: https://github.com/aerostitch/gnome-shell-pomodoro-debian.git
#Vcs-Git: git://git.debian.org/collab-maint/gnome-shell-pomodoro.git
#Vcs-Browser: http://git.debian.org/?p=collab-maint/gnome-shell-pomodoro.git;a=summary
Package: gnome-shell-pomodoro
Architecture: all
Depends: gnome-shell (>= 3.7), gnome-shell (<< 3.9), ${shlibs:Depends}, ${misc:Depends}
Description: GNOME Shell time-management app
This GNOME Shell app helps you to manage time according to the
pomodoro technique.
.
Features:
* puts a countdown timer in the GNOME Shell top panel;
* nags you with reminders about taking a break;
* uses full screen notifications that can be easily dismissed;
* hides other notifications until the start of the break;
* sets your IM (Empathy) status to "busy".
.
The pomodoro technique is a time and focus management method which improves
productivity and quality of work. The name comes from a kitchen timer, which
can be used to keep track of time. In short, you are supposed to focus on work
for around 25 minutes and then have a well deserved break in which you should
relax. Then when this cycle repeats for the fourth time you should take a
longer break (have a walk or something). It's that simple.
--- control.pristine 2014-01-28 20:14:49.180864433 +0000
+++ control 2014-01-28 20:27:52.942147796 +0000
@@ -12,24 +12,20 @@
Package: gnome-shell-pomodoro
Architecture: all
Depends: gnome-shell (>= 3.7), gnome-shell (<< 3.9), ${shlibs:Depends}, ${misc:Depends}
-Description: GNOME Shell extension manages time using Pomodoro technique
- This GNOME Shell extension helps you to manage time according to Pomodoro
- technique.
+Description: GNOME Shell time-management app
+ This GNOME Shell app helps you to manage time according to the
+ pomodoro technique.
.
Features:
- Countdown timer in the GNOME Shell top panel
- Full screen notifications that can be easily dismissed
- Reminders to nag you about taking a break
- Sets your IM (Empathy) status to busy
- Hides any notifications until the start of break
+ * puts a countdown timer in the GNOME Shell top panel;
+ * nags you with reminders about taking a break;
+ * uses full screen notifications that can be easily dismissed;
+ * hides other notifications until the start of the break;
+ * sets your IM (Empathy) status to "busy".
.
- What is the Pomodoro technique?
- The Pomodoro technique is a time and focus management method which improves
+ The pomodoro technique is a time and focus management method which improves
productivity and quality of work. The name comes from a kitchen timer, which
can be used to keep track of time. In short, you are supposed to focus on work
for around 25 minutes and then have a well deserved break in which you should
- relax. This cycle repeats once it reaches 4th break – then you should take a
- longer break (have a walk or something). It's that simple. It improves your
- focus, physical health and mental agility depending on how you spend your
- breaks and how strictly you follow the routine.
-
+ relax. Then when this cycle repeats for the fourth time you should take a
+ longer break (have a walk or something). It's that simple.
Reply to: