Proofreading LG

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.

Update the STATUS file. Add a line for the article and put an 'X' in the appropriate column (whatever you're working on.) The 'X' tells others that you are done with that section, and it's OK to work for someone else to work on this article. If you have to freeze the article pending an author revision, copyright question or other reason, put "HOLD" and the reason on the line.

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

Make sure the title and/or first paragraph accurately describe the scope of the article. Readers count on these to determine which articles are relevant to them. Reword the title and first paragraph if necessary, or contact the author to have them do so.

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

Fix the hyperlinks and IMG tags to supplemental files, putting URIs in the form "misc//". Add ALT=, WIDTH= and HEIGHT= attributes to IMG tags (we're trying for maximum access, and there are a lot of people who rely on these tags to provide meaningful content.)

Fix links to all other LG resources. Note that internal LG links, except for the ones that only exist at the root LG site (see below), must be *relative* rather than absolute (i.e., '../121/smith.html', not 'http://linuxgazette.net/121/smith.html'.) As well, all links to an index must be to 'index.html', not to the directory. These rules are necessary to make LG readable offline.

Link to an article in the same issue:

'<a href="[filename].html">'.

Link to an article in another issue:

../###/<author>.html
or (old issues)
../issue###/<author>.html

Link to a global file:

../faq/index.html

Absolute links are required to the search page and to CGI scripts since they don't work on mirrors or offline. *Occasionally* an absolute link to the home page is necessary, usually labelled "main site".

Remember to "svn add" any files and directories you create and to commit your changes promptly.

---

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

• No HTML headers or footers
• The first two lines must be

  author: author's_LG_name (usually the last name; see $SVN_ROOT/authors/)
  title: article_title
  

  and must be followed by a blank line.
  
  
• No <h1>s (reduce to <h2>s)
• No in-line CSS
• Minimize the number of tags wherever possible (get rid of &nbsp;s, etc.)
  
• Paragraph headings should be <h3>s
• Each paragraph should be preceded by <p> (optional for paragraphs immediately following the heading)
• Closing </p>s are unnecessary

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.