Usage tip o' the day

[Paul W. Frields]

TIP OF THE DAY:

If you use the word "this" or "that," follow it with a noun that
clearly indicates the antecedent.  Ensure that your use of "this" or
"that" isn't also an indicator of poor sentence construction.  The
word "lets" or "allows" following "this" or "that"
is generally a sign
that more editing is needed.

INCORRECT: "This shows the user who owns the process."
CORRECT:   "This option shows the user who owns the process."

INCORRECT:  "Turn on the 'updates-testing' repository in the Software
Sources tool.  This lets you test new packages before they are pushed
to the stable repository."
CORRECT:    "To test new packages before they are pushed to the stable
repository, turn on the 'updates-testing' repository in the Software
Sources tool."

Be on the lookout for naked "this" or "that"!

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Noriko Mizumoto]

Paul W. Frields さんは書きました:
>  TIP OF THE DAY:
>  
>  If you use the word "this" or "that," follow it with a noun that
>  clearly indicates the antecedent.  Ensure that your use of "this" or
>  "that" isn't also an indicator of poor sentence construction.  The
>  word "lets" or "allows" following "this" or
> "that" is generally a sign
>  that more editing is needed.
>  
>  INCORRECT: "This shows the user who owns the process."
>  CORRECT:   "This option shows the user who owns the process."
>  
>  INCORRECT:  "Turn on the 'updates-testing' repository in the Software
>  Sources tool.  This lets you test new packages before they are pushed
>  to the stable repository."
>  CORRECT:    "To test new packages before they are pushed to the stable
>  repository, turn on the 'updates-testing' repository in the Software
>  Sources tool."
>  
>  Be on the lookout for naked "this" or "that"! 
Thank you for pointing these out.
In terms of translation, I myself have experienced difficulties how to 
translate the naked "this" nicer more than once. This would be common in 
many other languages. Those corrections will be able to receive clearer 
translation in those languages too.

noriko

>  
>

[Chris Curran]

Paul W. Frields wrote:
>  TIP OF THE DAY:
>
>  If you use the word "this" or "that," follow it with a noun that
>  clearly indicates the antecedent.  Ensure that your use of "this" or
>  "that" isn't also an indicator of poor sentence construction.  The
>  word "lets" or "allows" following "this" or
> "that" is generally a sign
>  that more editing is needed.
>
>  INCORRECT: "This shows the user who owns the process."
>  CORRECT:   "This option shows the user who owns the process."
>
>     
It's often worth avoiding both usages here by not writing sentence 
fragments.
More correct: "Option -x shows which user owns the process"

>  INCORRECT:  "Turn on the 'updates-testing' repository in
> the Software
>  Sources tool.  This lets you test new packages before they are pushed
>  to the stable repository."
>  CORRECT:    "To test new packages before they are pushed to the stable
>  repository, turn on the 'updates-testing' repository in the Software
>  Sources tool."
>
>     
More correct: "Test packages not pushed to the 'stable' respository
by 
turning on the 'updates-testing' repository. "
>  Be on the lookout for naked "this" or "that"!
>
>     
You can be far more succinct and clear by making every sentence stand 
alone. If a sentence does not make sense without the sentence before it, 
consider revision.


Chris

[Murray McAllister]

> > CORRECT:    "To test new packages before they are pushed to
> the stable
> > repository, turn on the 'updates-testing' repository in the Software
> > Sources tool."
> >
> >
>
>  More correct: "Test packages not pushed to the 'stable' respository by
>  turning on the 'updates-testing' repository. " 
I do not think this is correct. It makes it sound like there are "test
packages" that are not pushed to stable, instead of users "testing the
packages".

[Paul W. Frields]

On Wed, Nov 26, 2008 at 11:58:12AM +1000, Murray McAllister wrote:
>  >> CORRECT:    "To test new packages before they are
> pushed to the stable
>  >> repository, turn on the 'updates-testing' repository in the Software
>  >> Sources tool."
>  >>
>  >>
>  >
>  > More correct: "Test packages not pushed to the 'stable' respository by
>  > turning on the 'updates-testing' repository. "
>  
>  I do not think this is correct. It makes it sound like there are "test
>  packages" that are not pushed to stable, instead of users "testing the
>  packages". 
I thought the same thing when I read it.  One must often balance the
desire for brevity with the need for clarity.

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Chris Curran]

Paul W. Frields wrote:
>  On Wed, Nov 26, 2008 at 11:58:12AM +1000, Murray McAllister wrote:
>    
> >>> CORRECT:    "To test new packages before they are pushed to the stable
> >>> repository, turn on the 'updates-testing' repository in the Software
> >>> Sources tool."
> >>>
> >>>
> >>>         
> >> More correct: "Test packages not pushed to the 'stable' respository
> by
> >> turning on the 'updates-testing' repository. "
> >>       
> > I do not think this is correct. It makes it sound like there are "test
> > packages" that are not pushed to stable, instead of users "testing the
> > packages".
> >     
>
>  I thought the same thing when I read it.  One must often balance the
>  desire for brevity with the need for clarity.
>
>     
Admittedly, my example was not all that great but my point is no less 
valid. Do not use 20 words when ten will suffice.
A minor edit with a little more thought.

Test new packages which are not yet in the 'stable' respository by enabling on the
'updates-testing' repository.

[Paul W. Frields]

On Wed, Nov 26, 2008 at 03:19:09PM +1000, Christopher Curran wrote:
>  Paul W. Frields wrote:
> > On Wed, Nov 26, 2008 at 11:58:12AM +1000, Murray McAllister wrote:
> >   
> >>>> CORRECT:    "To test new packages before they are pushed to the
> stable
> >>>> repository, turn on the 'updates-testing' repository in the
> Software
> >>>> Sources tool."
> >>>>         
> >>> More correct: "Test packages not pushed to the 'stable'
> respository by
> >>> turning on the 'updates-testing' repository. "
> >>>       
> >> I do not think this is correct. It makes it sound like there are "test
> >> packages" that are not pushed to stable, instead of users "testing the
> >> packages".
> >
> > I thought the same thing when I read it.  One must often balance the
> > desire for brevity with the need for clarity.
> >   
>  Admittedly, my example was not all that great but my point is no less  
>  valid. Do not use 20 words when ten will suffice. 
I agree completely with this guideline.  Short, declarative sentences
deliver information clearly and succinctly.

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

Some thoughts on beat writing

[John J. McDonough]

Now that Fedora 10 is in the box, I felt it might be useful to share some 
thoughts I had as a new beat writer, with an eye toward improving the 
process for Fedora 11.

The new beat writer is faced with three big challenges; 1) What is 
actually -IN- the beat, 2) What has changed and, 3) What level of detail to 
write about.  There are other hurdles to be sure, but these three seem 
almost insurmountable.

Geek that I am, I discovered that the answers to the first two can be (sort 
of) answered by rummaging around in the primary.sqlite files. 
Unfortunately, the PackageKit groups don't map precisely to the beats, and 
(IMO) there are a significant number of errors in the grouping, but these 
files contain the packages and their descriptions and versions, as well as 
the URL to the project.  By comparing versions between the rawhide sqlite 
file and the previous release, changes can be detected.  Once you see a new 
version the URL to the project (and sometimes the upstream's release notes) 
is right there. Unfortunately, you need to look at two different files, and 
you need to have some way to identify what packages actually are in your 
beat, so for me the path of least resistance was to import the whole shebang 
into MySQL.  Obviously, that wouldn't be the right path for most beat 
writers.  Also unfortunate that I didn't really discover this until late in 
the game, and my beats don't reflect this.  I'll do better next time.

The guidance I got initially was to follow the features pages and rummage 
around in bugzilla.  Bugzilla is too slow and too noisy to be very useful 
for this sort of exercise, and the features pages only deal with the major 
changes.  A lot of packages get updated, and although in the context of the 
entire release these may be minor events, when viewed through the microscope 
of a user of that particular package, it could be quite a big deal.  I was 
also advised to watch the commits, but I never did learn how to actually do 
this, and I suspect that would have the same noise problem as bugzilla.  I 
do watch the RSS feed on commits, but there is just too much going on there 
to pick out the relativly few I care about.

The other issue that should be addressed in the notes is the tension between 
what's there, what's changed and what's new.  I think the games guys did the 
best job on what's there.  They had a nice, short description and a link to 
a wiki page with the details.  Unfortunately, they didn't address the what's 
changed.  I suppose in principle the release notes ought to only reflect the 
differences, but we really need a "what's there" that is approachable.  The

new user can't really make sense of 11,000+ packages, and although the 
PackageKit grouping helps some, it doesn't help enough.  Many beats are 
really descriptions of what's there, sometimes to the detriment of what's 
changed.  One interesting aspect of this is that what the new user needs has 
a tremendous overlap with what the new beat writer needs.

I'm thinking each beat needs two wiki pages.  One for what will end up in 
the release notes, and another for what is actually in the beat.  The 
release notes page could direct the reader to the wiki what's there page for 
a full description of what Fedora offers on the particular subject, but the 
release notes content should be prefaced with a (very) brief description. 
In a lot of cases, there is a need for some (sometimes a lot) of nesting of 
pages.  I'm not sure if the intent of the page renaming exercise is to 
eliminate this entirely, but for example, in Software Development there is 
Runtime and Tools, and within both there are hundreds of packages.  There is 
some very uneven hierarchy in Tools, but not nearly enough.  I hit the 
biggies on this release, but Im sure there were dozens of changes that were 
missed and that were important to someone.  Long lists of paragraphs are 
hard to navigate and hard to maintain, so some structure is needed.  This 
structure can probably best be provided by including lower level pages in 
higher level, I suspect the page names aren't all that important.  But the 
page naming thing still worries me.

At this point I now understand how I will attack Fedora 11.  I realize that 
my approach isn't particularly helpful for most people, so I won't outline 
it here, but I am noodling on how we might help future beat writers.  I 
wonder if other beat writers, especially new beat writers, faced similar 
challenges and how they addressed them.  I suspect we (maybe even I) can 
make things a lot better for future beat writers, but then maybe I'm just 
dumber than the average bear.

--McD

Some thoughts on beat writing

[Paul W. Frields]

On Wed, Nov 26, 2008 at 10:37:51AM -0500, John J. McDonough wrote:
>  Now that Fedora 10 is in the box, I felt it might be useful to share
> some 
>  thoughts I had as a new beat writer, with an eye toward improving the  
>  process for Fedora 11. 
[...snip...]

Hi John,

Two recommendations:

1. Make a new post (instead of a reply) for new ideas so they don't
get lost in threads that people may be ignoring or marking read.

2. Can you boil this down into a couple succinct recommendations for
how we might do better at Beats for F11?


-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug