Writing for OSTG: A descriptive and enticing headline James Q. Author http://www.authorsite.com (If you prefer, you can use an email address, but the spam harvesters will grab it. You may be able to obscure it from some dumb harvesters by encoding it using an email address hider.)

This article will teach you everything you need to know about writing for OSTG. If you follow these guidelines faithfully, you can sell every piece you submit.

Well, not really -- but the above paragraph illustrates what we like in an opening paragraph: dynamic and compelling statements and information that will entice readers to click on the link to read the full story. That's important, because the first paragraph of the story is the only one that appears on the main page.

This "article" is actually a template you can use for your article. It illustrates what we like in submissions.

Give your file a name that indicates who it's from and what it's about. For instance, if your last name is Author and you're writing about, for instance, tuning Apache server settings, call it Author-Apache.txt, or .htm.

Aim your article at a reader who is an IT professional. Write as if most readers will know the basics, but provide hyperlinks to terms and products that might be unfamiliar.

Omit unnecessary words. Make every sentence contribute to the point you want to make. Use paragraphs as your arguments. Go through a piece and ask, is this word/clause/sentence/paragraph really necessary? Does it add to the reader's understanding of the topic? Once you've taken out any fluff, go over it again and ask, do my paragraphs flow clearly from one to the next? Do my arguments build logically on each other?

Here are some writing tips. In their format you can see an example of how to create a bulleted list:

Avoid passive voice. Whenever possible, rewrite sentences to make them active. You can usually rewrite sentences that begin with "There is" or "There are" to make them more active.
Avoid future tense.
Avoid cliches and overused phrases such as "That's where ProductX comes in," "Enter ProductX," and "last but not least." Cut phrases like "Please note that ..." and "The interesting thing about this is that...."
Spell out all abbreviations on first reference: "Open Source Technology Group (OSTG)"
Spell out words on first reference: say "application" before you refer to "apps."
Spell out numerals less than 10, unless they refer to amounts with units. Use numerals for numbers greater than nine.
When attributing quotes, use present tense: "Smith says" rather than "Smith said," or even worse, "said Smith."
Use the same capitalization for a product or project name that its creators use. If the creators aren't consistent, pick one and use it consistently yourself.

And a couple of technical tips:

Make sure you haven't saved the story file with a line break at the end of every line. Lines should flow one into the next, with breaks only at the end of paragraphs.
Use only one space between the period at the end of one sentence and the start of the next.
Put links around relevant terms, not around the word "here," as in: Download the software, rather than "you can download the software from here."

Bulleted lists are good ways to summarize related information, but they should not constitute a large fraction of an article.

Use <blockquote></blockquote> tags to set off large blocks of text, but use blockquotes sparingly. Don't rely on blockquotes for an article that's an interview. Instead, turn the subject's answers into a story, or use alternating paragraphs of questions and answers, with <strong></strong> tags around "NF:" and the subject's initials preceding alternating paragraphs.

Note the line below. It's the proper format for a subhed. Use subheds to break up the text in your article after each logical section. Subheds provide visual relief for readers' eyes, but they don't act as transitional devices; you still may need a transition sentence at the beginning of each new section to get the reader from the old topic to the new one -- see below.

Formatting the article

Once you've written your piece, paying attention to all this advice, you're ready to save it and submit it. We request finished submissions be in basic HTML format. We frown on StarOffice or OpenOffice.org format, and Microsoft Word files. If you generate your HTML from OOo, Word, or Nvu, please go through it and remove all the extraneous tags those programs add, or use one of the utilities or sites available to do the job for you. Also, run the document through a spell checker.

Please close your

and

tags. Use

tags rather than

, or for subheds within the body of the text. Use tags for commands and tags around variable information. For example: Run commandname option filename. Note that we do not enclose filenames in code tags unless they are part of a command.

If you are explaining how to run a command from a menu, use this format: "Click File -> Save As."

If you need to include a table in your article, use the following HTML code:

This is a table example
Column header	Column header
total data	total data
data	data
data	data
data	data
data	data

Use codes from the HTML document character set for symbols that must appear in text. For instance, if you need to represent a tag, open and close it with < and > rather than < and >.

If your article is more than 1,200 words in length and you feel the need to split it across multiple pages, use the pagebreak tag above to indicate that.

If you have some information that doesn't quite fit in with the main thrust of the article, consider making it a sidebar. Use this code for sidebars:

If you want to illustrate your text with images, we welcome screenshots in GIF, JPG, and PNG format, and video in SWF format. Put a comment in the body of the article at approximately where the image should go, and include a cutline if one is necessary:

Be sure to attach your screenshot to the same message to which you're attaching the article text. If your image is larger than 350 pixels in width, or is a video, please create and attach a thumbnail image to accompany the screenshot that is 350 pixels wide.

End your article with a paragraph that sums up what you've covered, or provides a vision of how the subject will affect readers. What does it all mean? What can we expect in the future?

At the end of your article, please include a brief bio that includes any special qualifications you have that make you an expert on the topic you're writing about and help readers find you credible. The bio should appear in italics.