...making Linux just a little more fun!

Proofreading LG

Last updated Sun Jun 13 15:14:32 EDT 2004
This page maintained by Benjamin Okopnik

First steps

So you've decided to become a proofreader for the Linux Gazette. First, thank you for offering your time and effort - it's sincerely appreciated! You'll be doing something great for the Linux community, and helping yourself by learning the job at hand as well as gaining knowledge about Linux itself: part of proofreading for LG involves technical review, however much of it you can do (there are other mechanisms in place to back you up, so don't worry about being perfect in this regard.)

The first requirement of this job is access to our Subversion repository - that's what we use for version control. This requires several steps:

  1. Email your SSH public key to the editor (). This will be used to grant you access to the repository.
  2. Install a Subversion client on your machine (e.g., "apt-get install subversion" for Debian users).
  3. Read and follow the SVN setup procedure, which will create a working copy of the repository on your system.
  4. Familiarize yourself with the description of the SVN structure in $SVN_ROOT/doc/files, especially the part related to the STATUS file.
  5. Recommended but not required:
    • Join The Answer Gang. Many LG-related issues, including proofreading, are discussed in TAG. See the Members FAQ for details.
    • Create a "home" directory for yourself under the "$SVN_ROOT/p/" subdirectory of your working copy. This way, anything that you're working on but are not yet ready to release will become part of the repository - very handy in case your hard drive dies [so speaks bitter experience. :) ]

There are three major areas of the repository that you will use as a proofreader: articles/, doc/, and p/. These are, in order, where the issue content is kept, documentation on the various aspects of SVN and LG-related work, and the per-user "home" directory structure.

The Proofreading Process

Before beginning any work, run "svn update" to bring your working copy up to date.

Check the STATUS file in the issue directory. Articles ready for review have an 'X' in the RELEASED column, nothing in the REVIEW column, and no "HOLD" message. Choose an article and put your initials in the REVIEW column. "svn commit STATUS" immediately to let everyone know that the article is being processed.

Proofreading

Run a spillchucker over the file and look for grammar and phrasing bugs. American and British spellings are both acceptable.

Clarity and conciseness are paramount; many of our readers have a limited knowledge of English (although technical explanations need to be explicit and clear regardless of the audience.) Minimize colloquial phrases and unnecessarily obscure words. Reword or explain phrases not understood across all English dialects. (E.g., "petrol" is OK, "dodgy" is borderline, but "trolley" for a wheeled cart had better be explained.)

If the wording sounds really foreign (e.g., "Indian English", "Dutch English", "Russian English"), try to fix the most jarring constructions, especially those that will trip up speakers from other non-English backgrounds.

Technical review

Is the article technically correct? Most importantly, does it contain bad advice that would make readers shoot themselves in the foot? If you believe that a part of an article is incorrect but cannot fix it yourself, add a ***FIXME*** tag at the beginning of the problem section, and put a HOLD on the article with "Technical review needed" as the reason (this will be a red flag to the various bulls who browse these pastures.)

When all technical problems are fixed, put an 'X' in the REVIEW column. "svn commit STATUS" immediately.

HTML check

Recap of the LG "sorta-HTML" article format:

Convert literal special characters to entities: 

    < to  &lt; 
    > to  &gt; 
    & to &amp;
These are especially common in inline program listings.

Run the article through HTML Tidy, ignoring the following errors (occuring due to lack of HTML headers): 

line 4 column 1 - Warning: missing <!DOCTYPE> declaration
line 4 column 1 - Warning: plain text isn't allowed in <head> elements
line 4 column 1 - Warning: inserting missing 'title' element

When done, update STATUS for the article by setting the appropriate columns to 'X'. Check your work into the repository by running "svn commit" (be careful not to run "svn update" instead, or you'll lose all your work!)

In case of any questions, problems, or errors, please contact either the proofreading team coordinator or the editor.

Tux