Delphi Informant Magazine
An Informant Communications Group Publication


Contributing Writer Style Guide


Thank you for your interest in writing for Delphi Informant Magazine. Especially 
since the first copy of Delphi Informant does not yet exist!

To give you some idea of what to expect from Informant Communications Group 
and Delphi Informant, Id like to tell you a little about our organization and our 
first publication, Paradox Informant Magazine. Paradox Informant Magazine 
began as a humble user group newsletter in 1990, with a circulation of less than 
100. As of this writing (11/94), Paradox Informant is read by over 30,000 
database professionals in 50 countries.

The success of Paradox Informant has been based on several factors. First, the 
editorial staff is made up entirely of database developers and technical editors. We 
are not journalists who decided to publish a database developers magazine. We 
are, instead, developers who ventured into journalism to publish high-quality 
technical periodicals. From its inception, the goal of the Informant 
Communications Group was to produce a magazine -- Paradox Informant -- that 
we would subscribe to ourselves.

This is an unorthodox approach to the magazine business, but we are very proud 
of the results. If youre unfamiliar with Paradox Informant, you can check it out at 
any major bookseller. Id like to draw your attention to another feature of the 
magazine -- the advertising-to-editorial ratio. The rule of thumb for the business is 
a ratio of at least 1-to-1, or one page of advertising for each page of editorial. I 
say at least because this is considered a minimum; the ratio is often 2-to-1 or 
higher. Again, Informant Communications publications defy the conventional 
wisdom. The routine ad-to-editorial ratio for Paradox Informant is 1-to-3. 
Obviously, this is a feature that readers appreciate.

Also critical to the success of Paradox Informant are the high-quality technical 
articles contained in every issue. Paradox Informant has enjoyed the good fortune 
of having skilled writers contribute their considerable talents to what has become 
one of the most respected product-specific periodicals in the world. 

Delphi Informant
We have the same plans for Delphi Informant. It will be a Delphi magazine for, 
and by, professional client/server and applications developers.

Which is where you come in. If you enjoy writing and are willing to share your 
expertise with fellow Delphi professionals, please read on.

We expect Delphi to be a popular product. If youve worked with it even for a 
short time, you know that no other application development environment can 
match its power and ease-of-use. And with its ability to produce free-standing 
executables and its genuine object-oriented, component-based architecture, we 
consider it an important and exciting development environment.

Delphi Informant Magazine will be a monthly publication of approximately 100 
pages devoted to the Delphi developer. Like its sister publications, Paradox 
Informant and dBASE Informant, articles will be divided into three skill levels -- 
beginner, intermediate, and advanced -- to provide comprehensive coverage of 
Delphi for developers at all points on the learning curve. Delphi Informant will 
also contain articles of interest to users of Borland Database Engine (IDAPI), 
Borland SQL Link, third-party packages that relate to Delphi, and -- of course -- 
all facets of client/server development: various RDBMSs, middleware, relational 
database technology, multi-user issues, stored procedures, triggers, event alerters, 
ad infinitum.

Articles
Delphi Informant is a technical magazine. Therefore, all articles submitted to 
Delphi Informant must contain a strong component of technical information. This 
component can take several forms, including -- but not limited to -- the following:
* An exploration of a particular feature or technique (e.g. creating a DLL, or  
updating a distributed database with two-phase commit).
* A comparison of two or more techniques to accomplish a task (e.g. data 
warehousing vs. real-time RDBMS architecture, or VBXes vs. Delphi 
components).
* A demonstration of a tool or utility you have developed (e.g. a query-by-form 
utility).
* A case study that demonstrates how a real problem was solved at your business 
(e.g. communicating with a remote host using a DLL, designing a database to 
fit your business rules).

Since Delphi Informant is a technical magazine, it is very important that all 
information be technically accurate. Although all material is tested by Delphi 
Informant before it is published, you should make every effort to be sure that the 
techniques you present are sound. Your terminology must be equally sound. This 
is discussed further below under "Conventions" and "Writing Style".

Deadlines
Deadlines are one of the more important aspects of publishing. Although getting an 
article in before the deadline does not guarantee that it will be published in a 
particular issue, missing the deadline guarantees that it won't.

Having said this, it's important to stress that it is far more important to submit an 
accurate, well-written article, than it is to meet a particular issue's deadline. There's 
always next month.

Here's the deadline schedule from the premier April 1995 issue, through the 
December 1995 issue:

 Issue    Deadline
-------   --------
Apr '95   01/01/95 
May '95   02/01/95 
Jun '95   03/01/95 
Jul '95   04/01/95 
Aug '95   05/01/95 
Sep '95   06/01/95 
Oct '95   07/01/95 
Nov '95   08/01/95 
Dec '95   09/01/95 

Submitting an Article Abstract
If you have writing experience or feel confident with your writing skills, please feel 
free to send us an entire article. Even if you are an experienced writer, however, 
it's a good idea to send an article abstract before taking the time to write an entire 
article.

An article abstract is a short description of the article you are proposing. It should 
give a good idea of the topic and techniques that you plan to address in your 
article, as well as its scope. It should convey enough information to allow Delphi 
Informant editors to accept or reject the proposed article. It should contain 
applicable contact information: phone number, fax number, e-mail address, and 
mailing address. It should also describe your writing and programming experience.

Common reasons for rejection at this stage are that the topic is not appropriate for 
the magazine or has been covered recently. If the abstract is approved, youll get a 
go ahead from an Informant editor. Then its time to start writing the article. It's 
important to note that approval of an abstract does not guarantee that the resulting 
article will be published. The article itself must then go through a stringent editorial 
process.

Submitting an Article
Delphi Informant can accept articles in the following IBM PC word processor 
formats:
* Microsoft Word for DOS or Windows
* WordPerfect for DOS or Windows (except for WordPerfect for Windows 
version 6)
* Microsoft Write 

If you cannot provide your article in one of these formats, just send it as an ASCII 
text file. Please use as little formatting as possible (e.g. custom Word style sheets). 
All formatting will have to be removed, and just makes the article harder to 
process. Please do not add headers or footers.

Authors should provide color screen shots and accompanying captions. Note that 
all non-text objects in a Delphi Informant article are referred to as "figures". 
Please don't refer to Figure 1, Listing 1, Table 1, etc. Instead -- using the same 
example -- refer to Figure 1, the listing in Figure 2, and the table in Figure 3.

Should you require screen capture software, let us know and we can provide you 
with the proper tools. Please make all screen shots available as separate files, not 
just as graphics embedded within a word processing document. Also give the 
screen shot files meaningful names (e.g. FIGURE1.PCX, FIGURE2.PCX, etc.) to 
match the text. Whenever possible, try to capture more of the screen than less. We 
can always crop the image. We can accept the following graphic file formats:
* pcx
* bmp
* tif
* gif
* tga

We can prepare any special graphics, diagrams, or other custom touches that your 
article might require (e.g. a diagram that illustrates an object class hierarchy). It is 
not necessary that you provide us with the finished art work. Just mock up a 
reasonable facsimile of what you want and we can probably create it.

This goes for screen shots as well. If you cannot prepare all the screen shots that 
an article requires, we can probably get the shots for you. As with all figures, just 
provide us with a reasonable description of what you're after.

Articles must be accompanied by all objects discussed in the article (e.g. PRJ, 
FRM, and PAS files, etc.). If your article involves objects and/or files, you must 
provide them in a form that can be run. This is because we must be able to test the 
material, and may need to take screen shots. We also want to place all objects that 
relate to an article on that month's Delphi Informant Companion Disk, the 
Informant Bulletin Board, and on the upcoming CompuServe Informant forum.

Although it is not required, CompuServe is the preferred method of 
communication and file transfer. The Internet is also fine for messages, but 
unfortunately, not for file transfers. Please compress all files using PKZIP or LHA 
before sending them via electronic mail. Articles can also be mailed on 3.5" or 
5.25" diskette. It is not necessary to include a hard copy of the article with mailed 
submissions. Fax is fine for messages, etc., but please do not fax articles.

The order of preference for file transfers is:
     CompuServe
     Informant Bulletin Board
     US Mail, UPS, etc.

Mail article submissions to:
     Delphi Informant
     Jerry Coffey
     Editor-in-Chief
     10519 East Stockton Boulevard
     Suite 142
     Elk Grove, CA  95624-9704

E-mail article submissions to:
     CompuServe: 70304,3633
     Informant Bulletin Board: (916) 686-4740

Messages and general contact:
     Phone: (916) 686-6610
     Fax: (916) 686-8497

Conventions
Delphi Informant is dedicated to delivering high quality articles to its readership. 
For this reason, the following conventions must be adhered to by all contributing 
writers. This is not meant to declare a proper or improper style, but to convey a 
consistent style to the readership.

In general, we attempt to emulate the typeface and case conventions used by 
Borland in their documentation. Object Pascal methods, procedures, functions, 
objects, components, events, properties, etc., should conform to the mixed case 
used in the Borland manuals (e.g. the LoadFromFile method, the TIcon object, the 
TButton component, etc.). Similarly, Object Pascal keywords should appear in 
lower case (e.g. procedure, begin, do, if, etc.).

Writing Style
All material should, of course, adhere to the normal rules of good writing. Here is 
a quick list:
* Use complete sentences.
* Organize your article, keeping like ideas together.
* Provide smooth transitions from one topic to the next.
* The level of detail should flow from general to specific.
* Each article should have an introduction and a conclusion. If an article does not 
have an engaging introduction, it might very well not be read. The lack of a 
conclusion gives an article an unfinished quality.
* Avoid clichs (e.g. best thing since sliced bread).
* Avoid sexism. All developers are not males and all users are not females.
* Use the exclamation point sparingly -- frequent use weakens its power. Also, 
adding an exclamation point to the end of a long sentence does not make it 
exciting. Exclamations are usually not complete sentences.
* It should go without saying that the material should be your own. Plagiarism 
will not be tolerated. At a minimum, any writer guilty of plagiarism will be 
permanently banned from writing for the Informant Communications Group. If 
an important part of your article comes from an idea you read somewhere else 
(e.g. a book) use the source as a reference. This does not diminish your 
contribution, and in fact, adds credibility to your material.

Then there are the guidelines that apply specifically to writing for the Delphi 
Informant:
* The bulk of any article should be explanatory text; code listings and bullet items 
do not an article make.
* Write to an audience at a particular level of expertise. For example, a beginner 
Object Pascal piece should not assume that the reader knows what a switch 
structure is. On the other hand, don't bore the reader of an advanced Object 
Pascal article with step-by-step instructions for opening the Code Editor 
window.
* This type of writing is jargon-filled by its nature. Please don't add unnecessarily 
to the techno-babble (e.g. use "procedure" not "proc", "application" not "app", 
"dialog box" not "dialog").
* Control the scope of the article. For example, don't try to tackle too large of a 
topic, or introduce a train of thought without concluding it in some fashion. 
Please feel free to refer to the Borland documentation (e.g. a page or a chapter 
in the Delphi Users Guide) if it helps to make the topic clearer or can provide 
background information outside the scope of the article. Also feel free to use 
previous Delphi Informant articles for the same purpose.
* Try to avoid the use of first person (e.g. "I'm writing this article to point out ..." 
should be "This article points out ..."). This includes the "story telling" style of 
writing (e.g. "This caused me to sit back and scratch my head for a while.").
* Keep the article in the present tense.
* Don't put a sub-heading over each paragraph. Sub-headings are great for 
demarcating sections of an article or to help with transitions, but don't rely on 
them for every transition.
* Be precise in your writing. For example, theres a big difference between a class 
and an object. Such items shouldn't be referred to interchangeably or 
ambiguously.
* Use comments frequently in your code. Algorithms and Object Pascal methods 
whose purpose is obvious to you may not be obvious to readers. Comments 
help explain your code and make it easy for readers to move between the code 
listing and the explanatory text in the article.

That's a lot of rules! Remember however, that these are guidelines -- not 
unwavering laws -- and they can be broken to achieve an effect. However, you 
should be aware when your article wanders outside these guidelines. These 
guidelines should be broken on purpose, not through ignorance. Use your best 
judgment.

Article Length & Other Requirements
As a rule of thumb, an article should have between 1750 and 6000 words. 
However, minimum and maximum lengths are not strictly enforced. Take as much 
(or as little) space as you need to properly convey your topic. Articles longer than 
6000 words are welcome. However, articles longer than approximately 8000 
words may be serialized. Here is the usual breakdown of article lengths:
* Average -- 2000-2500
* Long -- up to 8000
* Short -- 1000-2000
* Quick Tip -- less than 1000

Try to balance the number of figures to the article length. For example, a 2000-
word article might have 6-8 figures, whereas a 3000-word article could have 10-
15. However, it is also possible that a long article be almost entirely text, or a 
relatively short article be "figure-heavy". Just try to keep in mind how the article 
will appear in the magazine and attempt to strike a balance. (As noted above, code 
listings are considered figures.)

Suggested Article Topics
Please use your imagination! The direction of Delphi Informant is in a large part 
provided by its writers. It is the policy of the magazine to go where the writers 
lead. This helps to insure that the magazine's content reflects the current state of 
thinking of the Delphi community.

However, if you're stumped for topics, here's a list of general subjects that might 
help generate an idea. But please do not limit yourself to these topics:

Programming 
   Object Pascal techniques 
   Object-oriented programming
   The Delphi object model, manipulating events, etc.
   Designing classes and class hierarchies
   Delegation
   Class references 
   The Visual Component Library 
   Using the Graphical Debugger
   Capabilities of a particular Object Pascal class/method/property
   Exception handling
   Controlling user input 
   Creating and/or using DLLs
   Creating and/or using Delphi components 
   Compiler issues, e.g. directives, macros
   Using VBXes
   Using the Windows API
   Group programming issues (e.g. version control)

Client/Server / Database / Connectivity 
   Working with Visual Data Objects
   Client/server architecture
   Concurrency, data integrity
   Upsizing, downsizing, rightsizing
   Database design, normalization issues 
   Stored procedures, triggers, event alerters, etc.
   Borland SQL Links
   Borland Database Engine / IDAPI
   Distributed databases
   Using the Local InterBase Server
   Client/Server Express
   Using specific RDBMSs (e.g. Oracle, Sybase, MS SQL Server, Informix)
   Middleware (e.g. ODBC, MAPI, OBEX, etc.)
   
General 
   Getting Started with Delphi 
   Form design
   ReportSmith
   Interoperability with other Windows applications
   Getting the most from Delphis open architecture
   Rapid application development  
   Modifying the Delphi environment 
   The Object Browser
   The Project Manager
   The Menu Designer
   Designing and building on-line help
   Using Experts
   Using the Database Desktop
   Getting the most from Delphis editor 
   Creating Experts
   Network issues
   Performance issues 
   Undocumented features
   Using OLE 2.0 and/or DDE

Please keep in mind that well need beginner, intermediate, and advanced-level 
articles for all topics. Also note that although there will be some regular 
contributors that appear in the magazine often -- even monthly -- Informant 
Communications Group considers it important to publish the best articles we 
receive, regardless of the author's tenure. We are more than willing to publish the 
work of new contributors. High quality articles are always welcome.

Benefits to the Author
By contributing to Delphi Informant, you have a unique opportunity to establish 
your name and present your thoughts and techniques to thousands of Delphi 
developers across the United States and around the world. Contributing to the 
magazine can help further your Delphi career. Other contributors have obtained 
valuable leads and new clients as a direct result of writing for Informant 
publications. This is probably the greatest form of remuneration you will receive by 
writing for Delphi Informant.

To this end, with each article submission, please include a short, one-paragraph tag 
(or "bio") that will appear at the end of your article. At your discretion, it can 
contain a brief description of you and your organization. Although it is not 
required, it should provide some way for readers to get in touch with you (e-mail, 
phone, fax, etc.).

Delphi Informant also pays from US$150 to US$650 per article depending on its 
length and state of completion. In this context, "completion" indicates how well 
prepared the article is for publication. For example, is the writing quality up to the 
standards described above or will it have to be polished? The state of completion 
dramatically affects both the amount paid for the article and its chances of being 
published.

