A rough guide to Writing Technical Stuff for websites.

Submitted to us by Dave, M0UXB of the U.K.
Dave has a background in technical writing. This info has been slightly edited.

There is nothing more frustrating in seeing something in an article of interest and not being able to understand it. Professional Journals apart, the writer MUST assume that the poor sap reading it is ignorant. Now, don’t get me wrong. By ignorant I mean unknowing, not stupid. This can mean doing some clear drawings or explaining something using different phrases or words so it is.....simple!

It follows, then, that anything technical must explain ALL the necessary bits and not assume that we are all familiar with Kirchoff’s Law or Maxwell’s wave equations when trying to make a PSU....(what is a PSU?),  or simple dipole. Explain it properly.

Remember that the reader (or the Webmaster/editor) cannot see inside your head, and what’s simple to you might not be for him/them. What he or she sees is exactly what is in front of them, nothing more, nothing less.

Editors note: (There are many classes and levels of ham radio operators worldwide and no two have the same knowledge or technical skills as the writer may have. An antenna in the U.S. is an aerial in the U.K.! Coax shield and screen are one and the same in many countries but may have different meanings in others.  Be as specific as possible, your article may be seen around the world! Try to anticipate all questions and put the answers in the article before they ask you. You will save yourself and the reader much frustration and time explaining the same thing over and over in many emails to as many readers.)

Number the drawings. It’s easier to find your way about.

Don’t make the text too ‘friendly’ or use what may be unfamiliar phrases.

The reader may not be your nationality and therefore not understand.

Keep the language simple and spell correctly. Someone may want to translate it.

Unless you really are in a rush to get it out before the season is over or you’re going away, write it, draw it & read it. Then put it away and come back to it later and review it. You may see that it is not the article you intended to write or you see spelling errors that you missed before.

A simple format for your article or project!

1 Introduction.

Describe what the thing is and does, why it does it and the benefits of construction. Handy little items of Test Equipment are a good example of benefits. The increased range achieved by the new whiz-bang aerial is another. This is a good place to put the first illustration.

2 Necessary Parts

Opinion on whether this is the right place for it, or in a separate panel, is divided. But here is a good place to mention anything ‘special’ by way of bits (tripping over several feet of coax or tubing for that new aerial while you await the connectors or other bits is not funny). Here is the place to mention special suppliers (for example, of machined parts). And just because you are the lucky owner of a Hewlett Packard Vector Voltmeter, don’t assume the reader is similarly blessed.

If your new aerial works and you used a particular type of water pipe as a radome, or ONLY a certain size of wire, mention it here. The poor suffering reader might get the wrong stuff because you didn’t mention the type of tube (e.g., white water pipe, not grey or black). wire size, etc. You can even mention the maker.

3 How it works

Basic circuit descriptions and maybe a few references to standard circuits are inserted at this point.

4 Drawings

Make the illustrations CLEAR. It’s far better to have too many than too few. If each one illustrates a particular item, make sure there’s a drawing showing how these bits fit together.

For some reason unknown to this author, Webmasters seem to prefer GIFs, JPEGs & PDFs as the format for illustrations. I presume it has something to do with the transfer to the web page. I do know that Word97 files are OK for text, but horrible for drawings.
(Editor note: GIF, JPEG, and PDF files are, for the most part, standards for web presentation and work with the most popular browsers. Standard "text" formats using regular email clients work well also. A webmaster's nightmare is having to convert from one format, to another, to another to get the "item" to display properly on a web page!
No two different web browsers will display a web page as it was designed. Internet Explorer is THE most popular web browser in the world. This is what we design our pages around. Most web browsers will not have a problem with displaying all of the content on our pages, BUT, some may place various portions of the original design in different locations on the page than as originally designed and some will even "jumble" web pages into jibberish!.)

5 Testing

It is no use expecting all readers to have access to exotic test equipment, so make it easy to set up. For example, a decent VSWR meter for setting up an aerial, or an analogue voltmeter for monitoring a change in circuit conditions. If the reader is expected to make adjustments to get the project to work properly, tell him how to make them. Don't leave him "hanging".

6 Modifications, add-ons and enhancements.

It is at this point that adjustments for a more ‘personal’ project can be put in.

7 References & Suppliers.

You probably got the idea from some journal or other source. You DO need to say that you did and quote the Author, magazine and date. Technical references for some strange aspect of the project are also useful, (e.g., "Antennas" by Jasic, 2 nd Edition, page xxyy. Do not make the assumption that the reference you used is right unless it's the original text. For example, if you look up "Pawsey Stub" in Google or something, you’ll see several illustrations – all different. Make sure you get the right one that works for you and quote its source. This is also a good place to put in any necessary supplier details.

8 Layout

Number your pages and identify your drawings, pictures, etc. Leave plenty of white space in written documents. If sending the article by electronic means, don’t use an obscure font. Stick to Bookman, Century schoolbook or another good seriffed font, even if the final product is Sans Serif.
Another Editors note: Most of our webpages are displayed in"Arial" font. We have found that using this particular font displays much better on a greater percentage of computer monitors. So to help prevent us from having to convert "your" font, just send it in "Arial" and it will speed up the process. If you don't know how to change fonts on your computer, just send them as they are.
 
Don’t use a ‘compressed’ font (Times Roman, for example). It’s not what the font was devised for. Below are some examples of different fonts and how they display on a web page:

IT IS NOT,  NOR WILL IT EVER BE MY INTENT TO VIOLATE ANYONES COPYRIGHT TO THEIR MATERIAL! N4UJW

 SEND ME THE MAIL HERE
Use Subject of email such as "Ham Radio Project"
n4ujw@hamuniverse.com
Copyright N4UJW 2000 - 2007 Hamuniverse.com
Powered by HAM RADIO!