editors: Thread: Informational: [Fwd: Re: Review Complete: Linux Kernel 0.01 Commentary]

Hi all,

I just completed a rather exhaustive review on the new HOWTO mentioned
above (which is not yet added, due to a few outstanding changes
required, mentioned below).

I wanted to provide you with a copy of the email I sent to the author
after I completed the review.  Even without the files attached for you
to see, I thought this might be interesting to you all.  Sometimes just
seeing what another person does while on the job can give you ideas of
your own.

If you find all of this overwhelming, and something you don't think you
can do yourself, that's fine.  I only mean for this to be a glimpse of
my process, and using a real email seemed the most efficient way to do
that.  

As you can see by the author's response, having given him reasons for my
proposed changes, he is quite willing to work on the weaker points. 
This is ultimately our goal - if we can have the author take
responsibility and agree to the changes from the get-go, it makes things
go much smoother.

Please read over my email conversation below, and consider these things
during reviews, when you can.  You will find most authors cooperative;
I've never had a single issue with my revisions since I started, and I
think it has a lot to do with these kinds of communications.

Much thanks!
Tab


-----Forwarded Message-----
From: Pramode C.E. ####@####.####
To: ####@####.####
Subject: Re: Review Complete: Linux Kernel 0.01 Commentary
Date: Tue, 28 Oct 2003 01:11:50 +0000

Hello,

Thank you for the mail. I
shall definitely go through
all the points you have
mentioned and make all the
required modifications.

Regards,
Pramode C.E
------------



--- Tabatha Marshall ####@####.#### wrote:
> Hi, Pramode,
> 
> As mentioned in my previous email, please find your
> reviewed files in
> the attached archive.  I did a substantive edit for
> spelling, grammar
> and markup structure, ensuring that the markup is
> free from error as
> well.  Enclosed in the archive is also the html
> output after my changes.
> 
> I have a number of things to discuss with you. 
> There are some items
> that I've looked after for you, but others I will
> need you to take care
> of, due to time constraints on my part.  These are
> things that will
> significantly improve your document, and I will
> explain why as I go.
> 
> 1.  I removed repetitive words and corrected
> sentences by eliminating or
> using other words to represent: that, then, so, now,
> but, etc.  By
> removing them and restructuring the sentences, the
> reader is less
> distracted by them.  These are only a few of the
> words I changed or
> deleted - you can refer to the diff files for
> details, or read the
> source files if that's more comfortable.  
> 
> No action is required on your part other than to do
> a cursory reading
> and ensure I didn't change the meaning of anything
> when I made my
> grammar corrections.  
> 
> 2.  For words that have -ize/-ise, I went through
> all files and used the
> first instance I ran into, which was -ise
> (familiarise, organise, etc.),
> except, of course, for the <itemizedlist> tags.  I
> always go with the
> first instance I see and make the rest of the
> document consistent.  This
> goes for the spelling UNIX over Unix, and other such
> changes.  No action
> on your part is required.
> 
> 3.  Your <comment> tags do not appear in the final
> processed text, and
> aren't meant to.  You will need to go through
> (primarily) the i386.sgml
> file and close your <programlisting> tags, and use
> <para> tags instead
> of <comment> tags, or else your readers won't see
> the text.  Your
> attention on this is needed.
> 
> 4.  Wherever applicable, I added markup tags, such
> as <filename> to
> indicate files or directories, and <command>
> (self-explanatory).  I
> noticed your document could benefit from many other
> tags as well, such
> as <varname> for variables, <option>, and so on.  I
> encourage you to
> read the DocBook guide (www.docbook.org, and follow
> the link to the
> online book), and just scroll down the list of tags
> and familiarize
> yourself with the many things you can do.
> 
> The markup, as it stands at the moment, is correct,
> except for the
> graphics, which I will explain in another section. 
> You could also
> benefit from identifying each chapter and section by
> giving them IDs. 
> You can do this for any chapter or section using
> this syntax: <chapter
> id="intro">, and then proceeding with the title and
> so on.  This way you
> will get nicely named html files when processed. 
> Just a tip - no action
> required.
> 
> 5.  I removed extra punctuation, and tried to tone
> down
> opinionated/subjective comments, such as, "We don't
> know, find out
> yourself," as some readers find them derogatory.  I
> removed phrases like
> "of course" and "obviously" because what may be
> obvious to you might not
> be to the reader.  I encourage you to see how I
> smoothed them over or
> removed them, in some cases, to make sure I didn't
> take away the meaning
> of your text.
> 
> 6.  The markup syntax you used for graphics was
> broken in i386.sgml. 
> When you define the file, you do have to provide the
> extension, and none
> were there for the 6 images.
> 
> You will notice in the archive I sent back that I
> shrunk the pictures
> and saved them as jpg, using those as the filenames
> in i386.sgml.  The
> reason for this is because the graphics were coming
> out much too large
> in processing (with the ldp.dsl, which is what will
> be used).  2 are at
> 70%, 2 are at 60% and the other 2 are at 50%.  But
> they are still a
> little big.  Also, the figure titles in the images
> are confusing.  There
> is another way to do graphics using DocBook.  You
> can refer to the
> source for the Introduction to Linux-A Hands on
> Guide
>
(http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/Intro-Linux/chap1.xml?rev=1.6&content-type=text/vnd.viewcvs-markup
> will take you to examples contained in <figure>
> tags, in the first chapter, so you can duplicate the
> effort.
> 
> Please let me know if you can work on that, and if
> not, then when we get
> the other items taken care of, perhaps I can come at
> it again with fresh
> eyes and fix the graphics for you.  I'm just too
> tired and have to get
> moving on a couple other reviews.  Sorry!
> 
> This completes my review.  I'd appreciate if you
> could give attention to
> the items I pointed out above.  I don't necessarily
> need you to make
> more changes and send them to me.  If you can
> correct the above on your
> own, feel free to submit the archive back in to
> ####@####.####
> along with a note that I was the one who performed
> the review, and as
> soon as possible, it will be added to the
> collection.
> 
> I trust you'll want to make the doc look as good as
> possible before you
> resubmit it.  If you need help with the changes,
> drop me a line.  If you
> disagreed with anything, please let me know, and we
> can discuss it
> further.
> 
> Much thanks,
> Tabatha
> 
> On Fri, 2003-10-17 at 17:49, Pramode C.E wrote:
> > Hello,
> > 
> > Two weeks back I had subscribed to
> ####@####.####
> > and posted a brief description as well as a link
> > to the commentary I have co-authored (to be
> > considered for addition to LDP as a guide). I am
> resubmitting
> > the document as per your instruction.
> > 
> > Thanks and Regards,
> > Pramode C.E
> > ------------------
> > 
> >
>
______________________________________________________________________
> >
>
---------------------------------------------------------------------
> > To unsubscribe, e-mail:
> ####@####.####
> > For additional commands, e-mail:
> ####@####.####
> -- 
> Tabatha Marshall
> Web: www.merlinmonroe.com
> Linux Documentation Project Review Coordinator
> (http://www.tldp.org)
> Linux Counter Area Manager US:wa
> (http://counter.li.org)
> 

> ATTACHMENT part 2 application/x-compressed-tar
name=0.01-commentary-revised.tgz


________________________________________________________________________
Yahoo! India Matrimony: Find your partner online.
Go to http://yahoo.shaadi.com
-- 
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)