Last updated: March 11, 2006
First and foremost, please do not hesitate to ask if you have questions regarding these submission guidelines.
The VOICE Newsletter is a project that is completely based on volunteer work, which applies to authors,
publishers, editors, and translators alike. Nobody gets paid other than by possible sponsoring by our readers (as if
that's going to happen).
The complete staff donates their time to this project, yet they have jobs, families, friends, and hobbies. Please
consider this and help to minimize waste of time by following the guidelines below.
Here is how it works: You write an article and send it to editor@os2voice.org. If it consists of more than one file, please pack them with Info-ZIP. Please be sure your article is a valid (X)HTML or plain text file. If you submit an article as plain text, you may use Usenet- or e-mail-style markup for bold and italics. (X)HTML files need to use the VOICE Newsletter styles (see below).
There is no requirement as to length, since this newsletter is only in XHTML and INF format. It can be as long or as brief as necessary, so be thorough in your descriptions and commentaries. However, please remember that you are not writing your master thesis, so you don't have to begin at the very beginning à la "And first the earth cooled...". The reader will get bored very soon if you begin the review of a word processor with a nicely worked-out history of word processing software.
Your article will then be reviewed and run through a spell checker (something that you should also have done before sending the article). If there are any changes we think should be made that are not related to spelling or grammar, we will let you know and we can discuss them. We do not make any major changes without input and approval from the author. We will work on it with you to get it in shape. We are not professional editors, but we believe we have done some decent work on the Newsletter.
As to professionalism of writing, please refrain from vulgar and abusive language, illegal subject matter, and slander/libel. While a casual writing style ("writing as you would talk") can be acceptable or make sense in some cases — as a stylistic device, in editorials or glosses — we strongly encourage you to choose a more professional approach in general (this does not mean that you cannot be funny). Our aim is to encourage readership and author participation by presenting a tasteful, yet useful medium for OS/2 related information.
Sorry, but alas we cannot spare you the following. It is required for our and your own safety.
By submitting an article for the VOICE Newsletter you grant VOICE the irrevocable and perpetual right to translate, publish, store, and distribute the article (defined as text, included images and code) via any media without any compensation. You also grant VOICE the right to apply modifications to the translation if required for better comprehensibility. Otherwise you retain the full copyright. By submitting an article you also assure that it is free from copyrights of third parties, or that these third parties agree to the terms mentioned above, and that you are liable for any possible copyright infringements in your article (text, images, or code).
If you are not sure whether your idea for an article is suitable for the Newsletter, have a look at the following list of general kinds of articles:
Here are some concrete suggestions for topics that we think are of particular interest:
Before you start, take some time to think about the target group of your article: Who are you going to write for? This question is extremely important as quite a number of things depend on the answer. The target group determines what kind of knowledge can be taken for granted, as well as specific areas of interest. Furthermore, different target groups face different kinds of problems, and have different ways of tackling these.
A few words on style. Dealing with the question of How to say it?
in-depth is way beyond the scope of this
document but we try to give some directions.
There are several levels where you can move between extremes. There is much room for variety but please consider the following:
Too much of a good thing can kill you.
Many things are more efficient in small doses.
All kinds of article types share some common characteristics:
The following should give you a rough idea of what to include in different types of articles and how to do it.
Essentially, this type of article describes a product, service, event, or problem, the key characteristic being that it presents the author's personal experiences. This is usually done diary-style or anecdotically, i.e., the facts and events have a chronological or associative relation, not one of content.
As a result, and compared to other article types, the experience report is the easiest on the writer but also the hardest on the reader. It can be quite entertaining but the scattered facts and its subjective approach make it hard for the reader to see what information is essential.
Due to the above, experience reports are not found in professional media, except for a very restricted set of purposes. Generally, they are only used to report cases of, e.g., extremely bad support, or as glosses (see below). As far as the VOICE Newsletter is concerned, also reports about events are acceptable in this form, although we recommend a mixture of experience report and normal report.
A review presents your findings from a product test, a product being hardware, software, or a book. The following focuses on hardware and software but much also applies to book reviews.
If your article is a review, you should definitely read Esther Schindler's article How to write a product review from the November 2000 issue of Extended Attributes.
The article type of reviews has three subtypes that have slightly different purposes each:
Essentially, the article should contain the following parts:
Setup/Installation: Was it complete out of the box (or zip file), or did you have to purchase or find additional items like cables and drivers (this mostly applies to hardware)? Did you have to read the manual? Was there a manual, if so how good/helpful was it? Did you still have to boot to plain DOS or Windows to run any kind of setup or calibration software? What hardware are you using it with (major PC specs if applicable, i.e., CPU, RAM, HD) and what version of OS/2? Any minimum hardware/software requirements for this application? What kind of support is provided? Did you have reason to ask for help, if so how was the response?
What is it capable of and how does it work: What does the manufacturer claim that the product can do? Does it hold to this promise? Don't recite the feature list! Deal with the features that are interesting for the reader instead. Give some details on how you use the application. No need to get into every detail, just the basics is fine. Be aware that your way of doing things isn't necessarily the same as our readers'. Graphics and figures are nice and help a lot in showing how a product works.
If your article is a How-to, i.e., it explains how to achieve certain things with certain applications, tool, etc., please mind the following:
And, by the way, abc works by doing xyz.
Editorials give your personal opinion regarding a certain topic and often try to persuade the reader to agree with
you and, as a result, do certain things.
Glosses usually deal with a topic in an ironic or sarcastic manner. Sometimes, glosses are written as fake articles
of another type, e.g., reviews, reports, or interviews.
A common characteristic is the increased use of stylistic devices.
Editorials are not structured very strictly. Nevertheless, the following applies:
Glosses that are faked articles generally follow the structure of the faked article type.
Essentially, a report describes an event that the author has attended or a topic that the author has researched, the main difference to an experiences report being that the author himself takes a backseat and the focus lies on the topic.
While preparing the article, you may want to get some comments from people involved, i.e., visitors of an event or the ones concerned.
Interviews provide different ways to obtain answers to questions. The key question — which you have to
answer yourself — is What does the reader want to know?
or What information could be interesting for
the reader?
The answer to this determines who, how, and what you are going to ask.
There are different types and levels of interviews:
Interviews can have different kinds of focusses:
Depending on your target group, you may want to either choose a focus for an interview with a given person, or think about whom to ask about a given topic to get the desired information.
Apart from the general rules of conduct, there are a few things more to consider:
Formatting the text in certain ways can increase readability a lot. VOICE uses XHTML and CSS to define article structure and presentation. Please ensure that your article conforms to the following to keep the Newsletter's interface consistent.
For structuring an article and presenting information, the usual standard XHTML tags for headers, paragraphs, line breaks, lists (unordered, ordered, and definition), tables, etc. plus a number of special styles are available.
The first level header (<h1> tag) is reserved for the article title only, so article headers start at the second level. While XHTML supports up to six header levels, please avoid unneccessary complexity. In general, using the second to fourth level headers (<h2>, <h3>, and <h4> tags) should be enough.
No numbering of headers, please. The VOICE Newsletter is neither a scientific nor legal publication.
Use paragraphs and line breaks to illustrate your train of thought. Please note that while using long paragraphs with many line breaks is quite common in printed media, they are hard to read on a computer monitor.
Please use the different types of lists as they were intended to. Lists are not a replacement for headers!
Ordered lists should only be used if there actually is an order or priority in the sequence of list items, e.g., when consecutive steps for a setup are described. If the order is not important, the unordered list is the way to go.
When explaining a number of terms in a wider sense, e.g., terms, parameters, commands, etc., use a definition list. Please do not use tables for such purposes unless the information you present is tabularly and would require more than two columns.
Tables should be used to present tabularly information only. They are not a means for layout. If you want to list definitions of terms that would result in a two-column table, a definition list usually is the better alternative.
Always provide a caption that defines the table content. These should be numbered in the following way:
Tbl. 1. Performance test results for AMD Athlon processors
Provide headers that define the content of each column or row. Special styles are available for marking parts of a table or single cells.
Keep them simple: Please don't include images in tables and avoid nested tables since both kinds are not supported by IPF and make generating the INF version of the Newsletter very complicated. Furthermore, they make it hard for people with screen readers to understand the page.
Images can be in just about any format, but we prefer PNG, JPG, or GIF. Note that the different formats are also suitable for different purposes. JPEG is likely to result in washed out fonts in screenshots of dialogs, for instance.
Try to keep them to 256 colors or less (this is a requirement of the INF version), and the smaller the file size the better, as some people download the Newsletter to read off-line. If the image width exceeds 600 pixels, you may want to consider using thumbnails in the text.
You may want to mark relevant parts of an image with colored arrows, circles, or boxes to direct the readers' attention.
Always provide alternative text for people with text-mode browsers or screen readers, please.
Add meaningful captions below images. Usually, they can repeat the alternative text. These should be numbered in the following way:
Fig. 1. LAN interface setup dialog
Please see the following tables for a list of available styles, notes on usage, and examples. We have tried to keep style names as self-explaining as possible. Inline styles begin with a lower-case "i" and block element styles with a lower-case "b."
Unless explicitely stated, styles inside paragraphs are applied by enclosing the text like this:
<span class="classname">text to use a style with</span>
Where a tag is given in angle brackets, it has to enclose the text like this:
<tag>text to use a style with</tag>
Name | Usage | Example | Classname/Tag |
---|---|---|---|
With special tags | |||
emphasis | A newly introduced term that is used for the first time in the article, terms in foreign languages, slightly emphasized things. | This was the first time a computer was used for such calculations. | <em> |
strong emphasis | A strong emphasis, e.g., for a warning. | Do not format your drive unless you have a working backup. | <strong> |
acronym | An acronym or abbreviation. If you move the mouse pointer over the acronym, an explanation is displayed that is provided via the title attribute. For many widely-used computer abbreviations and acronyms, this will automatically be taken care of by our scripts. | V.O.I.C.E | <acronym title="long description"> |
code | Any snippet of program code in a wider sense. E.g., HTML, CSS, REXX, C, Pascal. | SysSetObjectData() |
<code> or iCode |
keyboard input |
Keyboard input to be entered by the user. A "-" or "+" between two keys means that they have to be pressed simultaneously. In the example, you would have to press both the "Ctrl" and "C" keys. |
[Ctrl-C] | <kbd> or iKeyboard |
quote | A quote from real persons or books, or program messages. Note that the browser adds quotation marks automatically. | You have selected to delete the file test.zip. Continue?or To be or not to be? |
<q> |
citation, quote source | The source of a quote. This could tell you whom the "To be or not to be?" quote from above originated from. | Hamlet | <cite> |
variable, syntax | A variable, variable name, or program argument. Often used to explain command syntax. | directory or filename | <var> |
With classes | |||
address | All kinds of addresses. | 192.168.1.1 or comp.os.os2.bugs | iAddress |
command | A command that has to be entered at a command line and executed by pressing the "Enter" key. | unzip test.zip -d x:\temp | iCommand |
command output | Output that is displayed by a program at a command line. | unzip: cannot find either test or test.zip. | iOutput |
entryfield | Text that has to be typed in an entry field. | The quick brown fox jumps over the lazy dog. | iEntryfield |
files, paths | The name of a file or folder, or its partial or fully qualified path in the file system. | CONFIG.SYS, OS2\INSTALL, or C:\OS2\BOOT\OS2DASD.DMD | iFile |
GUI elements, active |
For active GUI elements, which cause some action to occur when clicked: menu items, push buttons, checkboxes, radio buttons, lists, combo boxes. A ">" seperates elements that have to be selected consecutively. In the example, this would mean that you first have to select the menu item "File" and then "New." |
Browse or File > New | iGuiActive |
GUI elements, static | For static GUI elements, which are used for information purposes: window and dialog titles, group names. Groups are borders, usually surrounding several associated active GUI elements. | Shutdown | iGuiStatic |
WPS objects |
Workplace Shell desktop objects, both abstract and with a file system pendant. A ">" seperates such elements that have to be selected consecutively. In the above example, this would mean that you first have to open the "Local System" folder object, then the "System Setup" folder, and then the "Mouse" object. |
Templates or Local System > System Setup > Mouse | iObject |
Unless explicitely stated, styles constituing paragraphs are applied by enclosing the text like this:
<div class="classname">text to use a style with</div>
or
<pre class="classname">text to use a style with</pre>
General purpose containers (<div> tags) can contain other markup constituing paragraphs itself.
Name | Usage | Example | Classname/Tag |
---|---|---|---|
summary | The summary of an article. Usually located directly after the title. |
Emacs is an extremely feature-rich and extensible editor. However, these qualities have a price: complexity. Many people have surrendered to the steep learning curve that has to be overcome before one can take advantage of all the program's goodies. To help you avoid the same fate, this article describes the installation and customization of the Emacs editor in great detail. |
<p class="bSummary"> |
quote | Quotes that extend over several lines. |
The VOICE bylaws state:
So this organization is about OS/2. |
<blockquote> |
Classes for general purpose containers (<div> tag) | |||
header | A general purpose header that can be placed above any paragraph-style markup |
A header
Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's
intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the
time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in
the mid-1980's, it was quickly becoming obsolete.
|
bHeader |
digression | A box that contains side notes and digressions that don't otherwise fit into the flow of the article. |
OS/2 history
Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's
intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the
time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in
the mid-1980's, it was quickly becoming obsolete. Thus, OS/2 was born, initially as a 16-bit,
command-line based operating system. Microsoft worked closely with IBM up to version 1.3. While IBM worked on
the "guts," they worked on the new graphical user interface that was due for later versions.
OS/2's kernel was developed by IBM from the ground up as the Personal Computer (PC) version of a
mainframe operating system, with all of the time-slicing, stability, and other features previously existing
solely on those high-end machines.
|
bDigression1, bDigression2 |
entryfield | Several lines that have to be entered into an entry field or similar. |
The quick brown fox jumps over the lazy dog.
Then it escapes the hunter by hiding behind a bush. |
bEntryfield |
caution | An important note. |
While RSU is great to have on standard OS/2 systems, I don't recommend using it on eComStation systems.
The eCS Maintenance Tool provides its own method of installing FixPaks over the Internet, and it's
already much more advanced than RSU ever was. It also handles post-installation dependencies specific to
eComStation (like updating the dialog and icon resources), which RSU does not.
|
bCaution |
warning | A warning. Failing to abide by this instructions can lead to severe problems. |
Create a backup of your INI files before installing this software. It is still in beta state and could
completely break your WPS.
|
bWarning |
finished, checked | Notes about a larger section of work that has been finished and the consequences thereof. |
Now that we have finished the above configuration steps it is save to reboot the machine and start the server
for the first time.
|
bChecked |
reminder for later | Things to keep in mind. |
As you can see, the configuration steps executed above have changed the application's display the way we
wished. We need to keep this in mind for later, when we adapt the printout.
|
bPin |
success, ok | Specific characteristics that mark an operation's success. Something that is particularly positive about a piece of software or hardware. |
Congratulations! You have finished configuring the most versatile and complex editor ever developed!
|
bThumbsup |
Classes for preformatted text (<pre> tag) | |||
code | Several lines of arbitrary code. |
Example #1: xcenter.c from XWorkplace
SOM_Scope BOOL SOMLINK xctr_xwpMoveWidget(XCenter *somSelf, ULONG ulIndex2Move, ULONG ulBeforeIndex) { // XCenterData *somThis = XCenterGetData(somSelf); XCenterMethodDebug("XCenter","xctr_xwpMoveWidget"); return ctrpMoveWidget(somSelf, ulIndex2Move, ulBeforeIndex); } |
bCode |
command | Input and output at a command line. |
unzip notexist.zip -d x:\
unzip: cannot find either notexist or notexist.zip.
|
bCommand, bCommandOutput. Note that bCommandOutput can only be used with span tags inside a bCommand block. |
file content | Generic file content. |
Partial CONFIG.SYS
BUFFERS=100 IOPL=NO DISKCACHE=512,LW,32 MAXWAIT=1 MEMMAN=SWAP,PROTECT SWAPPATH=H:\ 10240 92160 BREAK=OFF THREADS=1024 PRINTMONBUFSIZE=2048,134,134 |
bFileContent |
In general, images have to inserted in general purpose containers (<div> tags). They are followed by a line
break and an image description.
Under certain circumstances, however, placing a caption may be completely superfluous or even ill-advised. In an
editorial, a cartoon with a caption that says Fig. 1. Cartoon explaining why xyz sucks
would be
unintentionally funny, for instance. Should that be the case and it is intended to let the text flow beside the
image, the image can be inserted directly into the corresponding paragraph and a class can be assigned to the image
itself.
Name | Usage | Example | Classname/Tag |
---|---|---|---|
image on its own | An image that has its own paragraph without text flowing to either side of it. |
Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in the mid-1980's, it was quickly becoming obsolete. ![]() Fig. 1. An image displayed on its own line Thus, OS/2 was born, initially as a 16-bit, command-line based operating system. Microsoft worked closely with IBM up to version 1.3. While IBM worked on the "guts," they worked on the new graphical user interface that was due for later versions. OS/2's kernel was developed by IBM from the ground up as the Personal Computer (PC) version of a mainframe operating system, with all of the time-slicing, stability, and other features previously existing solely on those high-end machines. |
bImageCenter |
left-justified image | An image with description and text flowing to the right of it. |
![]() Fig. 2. An image displayed on the left side Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in the mid-1980's, it was quickly becoming obsolete. Thus, OS/2 was born, initially as a 16-bit, command-line based operating system. Microsoft worked closely with IBM up to version 1.3. While IBM worked on the "guts," they worked on the new graphical user interface that was due for later versions. OS/2's kernel was developed by IBM from the ground up as the Personal Computer (PC) version of a mainframe operating system, with all of the time-slicing, stability, and other features previously existing solely on those high-end machines. |
bImageLeft |
right-justified image | An image with description and text flowing to the left of it. |
![]() Fig. 3. An image displayed on the right side Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in the mid-1980's, it was quickly becoming obsolete. Thus, OS/2 was born, initially as a 16-bit, command-line based operating system. Microsoft worked closely with IBM up to version 1.3. While IBM worked on the "guts," they worked on the new graphical user interface that was due for later versions. OS/2's kernel was developed by IBM from the ground up as the Personal Computer (PC) version of a mainframe operating system, with all of the time-slicing, stability, and other features previously existing solely on those high-end machines. |
bImageRight |
left-justified image inside of paragraph | An image without description and text flowing to the right of it. |
|
iImageLeft |
right-justified image inside of paragraph | An image without description and text flowing to the left of it. |
|
iImageRight |
Besides the normal cells, the following is available for formatting tables:
Name | Usage | Example | Classname/Tag | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
caption | Describes the content of the whole table. |
|
<caption> Placed directly after the table tag. | |||||||||||||||
header | Describes the content of a column or row. |
|
<th> | |||||||||||||||
category header | A sub-caption that describes the content of the following table columns and rows |
|
<th class="category" colspan="x"> Note that this has to get a colspan attribute assigned with x usually being the actual number of columns the table consists of. | |||||||||||||||
marker color 1 | A backgroundcolor for marking a table cell. | Test | <td class="mark1">Test</td> | |||||||||||||||
marker color 2 | A backgroundcolor for marking a table cell. | Test | <td class="mark2">Test</td> | |||||||||||||||
marker color 3 | A backgroundcolor for marking a table cell. | Test | <td class="mark3">Test</td> |
Again, if you have any questions regarding the submission itself or how to write an article, feel free to ask.
Thank you,
The VOICE Editors