撰写技术文章的方法诀窍

撰写技术文章的方法诀窍

A Guide To Writing Articles For Code Project
By Marc Clifton

A Disclaimer

I am not in any way involved in the administration of Code Project, and the administrators have not, in any capacity, asked me to write this article. This article is completely based on my own personal views and experiences in programming and technical writing. As the title states, this is a guideline, not gospel. As the user "Bill SerGio" wrote: "[an] article should have...CREATIVITY and each author should include their personal philosophy and views". The intent of this article is to provide some guidance and possibly some inspiration to potential authors. Within those (or any guidelines) there is lots of room for creativity and personal philosophy.

Why Write A Decent Article?

Visibility

Code Project has high visibility in the programming world. Besides a rapidly growing member base, it has a high hit rate when doing a keyword search on many programming terms using, for example, Google. Therefore, there is a chance that one of your peers may encounter your article. More importantly, I would, as an employer, not only ask if you have published any articles on Code Project, Code Guru, and other similar sites, but I would specifically search these sites for your work. For example, searching my name 揗arc Clifton?on Google reveals two articles I抳e written as the second and third hits (the first being 揂nglo Church Planting Strategist?-huh?)

Sure, you can hide behind an alias, but the people that want to use their articles as resume fodder would probably not do this. And resume fodder is important, even if we all detest it. Most likely, your motivation for writing an article has nothing to do with your resume or CV, but keep in mind that at some point you might realize that this is a side benefit.

Professionalism And Expertise

When writing an article, do you want to appear as a professional and an expert in your subject? It is in your best interest to write a professional article that defines you as an expert in your subject. Yes, there are degrees of professionalism and expertise. For example, there are articles that I can just 搊oh?at and hope to achieve in terms of the professional way that people have put code, text, and graphics together. Similarly, I am not an expert by any means, yet sometimes I feel that even something rather simple might be useful to someone else. Being an 揺xpert?can, loosely defined, simply mean 損roviding expertise to someone else? no matter how simplistic the subject matter.

Professional Courtesy

Other people, who mostly consider themselves professionals in the industry, or who are striving to be become more experienced (even a hobbyist), appreciate reading an article that shows respect for the community at large. Also consider that for many readers, English is not their first language. Therefore, if you are fluent in English, it is a courtesy to others to present your concepts in a clear and concise manner.

Why Write An Article At All?

I can really think of only one answer, since I抦 not getting paid to do this. And that is to make a contribution to the community. There may be secondary reasons, such as "it's fun". Whatever your reason though, I suspect that you want your article read by others. And that implies, that with anything else, you need to rapidly convince the reader that the article is professional, and that you are, to some small degree, shedding some expertise on the subject. Yes, there are those people that will read an article or even ignore the text and go straight for the code, regardless of "quality" of the article. This does not mean that you should write an article for the lowest common denominator. There are many people (like myself) that won't even bother reading an article if it appears to be poorly written. And there are very good reasons for this that perhaps the "go for the code" people miss, which I discuss later.

What Makes A 揇ecent?Article (at first blush)?

There are only a few things that make an article 揹ecent?and separate it from the rest of the pack. The first is visual presentation, or formatting. The second is spelling (I have a whole section on spelling later on, because this appears to be such a controversial topic). A third issue is the presentation of graphical elements. And finally, there is the issue of code formatting.

Note that almost none of my suggestions on writing a decent article have anything to do with content. This is addressed later.

Formatting

As a reader, I will immediately judge your article as to its professionalism by quickly glancing at the formatting. My personal opinion is that if an article appears well formatted, then the quality of the content is probably high also. While a poorly formatted article may have a high content quality, I think this is the rare case.

Formatting Graphics

Have you taken the time to crop your images, demonstrating a basic concept of such simple programs as Microsoft Paint, or does the reader get to see what beautiful background you are using on your desktop? Cropping your images shows respect for the editors because it saves them time from doing it themselves. It also shows that you care about the quality of your work by putting polishing touches in to it. Also, many people still use modems to access the Internet and do not appreciate long page load times because the author hasn't cropped his/her images.

A picture speaks a thousand words, they say. Do the images in the article provide an understanding of the article抯 concepts from a "visual" perspective? For example, is there a nice UML or similar diagram showing the class hierarchy? Are there screen shots showing the tool in action? Is there a diagram of the different technologies that are utilized and how they interface with each other? These are some examples and ideas for the purpose of images.

Formatted Text And Outlining

An article should have some kind of outline which is typically represented in the headers. The headers give the reader a quick summary of your thought process and the flow of the article. Consider what a table of contents might look like if constructed from your article's headers. It seems that outlining is a lost art. It would strongly recommend writing an outline before even beginning the meat of your article. This will help organize your thoughts. From personal experience, I have also found that an outline points out weaknesses in my article, such as vital yet missing information. An outline also has another advantage. Writing an article is a time consuming process. By writing an outline first, you save myself some time in organizing your thoughts. However, you can also save yourself considerable time by pruning your article of unecessary information.

Another aspect of formatting is to have a basic understanding of HTML. Here's a really brief guide:

<p> - paragraph separator
<br> - forces a line break
&lt; - the '<' character
&rt; - the '>' character
<h2> - the beginning of a main level header
</h2> - the end of a main level header
<h3> - the beginning of a sub-level header
</h3> - the end of a sub-level header

There are of course many other useful HTML commands, but I consider these to be the essential ones.

Code Formatting

One of the guidelines for code formatting is that the code should be readable without horizontal scrolling on am 800x600 display. There is an excellent tool that can be used to see how your article and its code looks on an 800x600 display:

http://www.codeproject.com/tools/windowsizer.asp[^]

Another aspect of code formatting is deciding what code to present and how much of it to present in a single <pre> block. A couple simple rules suffice梡resent only the code that is core to your point. Secondly, if a block of code takes up more than a screen, well, it抯 probably poor quality code. Therefore, consider that you might want to break the code apart into well defined functions, or you may want to show each function with some text describing what the function does. (Yes, yes, I know there are exceptions, and I'm not going to argue them.)

Spelling

An article that has not been spell checked is inexcusable (see #5 below for an exception).

It seems like that should be the end of the matter, but reading through the various responses to the first version of this article, it appears that some people disagree with the above statement. I have the following to say about that:

1. Spell checking is a courtesy to your reader;
2. Spell checking is part of the polishing process;
3. Correct spelling makes it easier for our global community to understand the article;
4. If English is not your first language, wouldn't it be nice to learn a few words, correctly spelt?
5. If you don't have an English spell checker, yes, you are excused;
5a. Better yet, when you post the article, as someone to spell check it for you;
6. You should be responsible for spell checking, not the editors.

Since we're on the subject of spelling, J鰎gen Sigvardsson wrote:

It would be nice too if you mention the ugliness of using "u" instead of "you", "4" instead of "for", etc. I can't think of sloppier writing than that.

This also points out that slang language should be avoided if possible, because our non-English as a first language readers probably won't understand it. For example, in this article I use the terms "resume" and "CV", both of which are localizations--not necessarily slang, but two words which mean basically the same thing, but whose meaning is not universally known.

Programmers Are Not Technical Writers
or: What Makes A Decent Article (at second blush)

Now that you have a well formatted article with pretty and informative pictures (or not), the headers have give an indication that you have actually put some thought into what you are saying, and code snippets (if any) have at cursory glance shown that you have some right to call yourself a 損rogrammer? your article might actually get read. Does this seem like a harsh statement? Good!

Let抯 face it. Programmers are not technical writers. A spell checker cannot tell you whether you抳e written a decent sentence. To address this, I抦 going to fall back on my Dale Carnegie training and suggest a few guidelines (while deviating considerably from Mr. Carnegie). These guidelines aren抰 just for newbies but for veterans also. Please keep in mind that these are just ideas. Many articles do not need to follow this outline.

What Is Your Subject Matter?

This should describe what you are writing about. It is usually placed in the introduction, and it is often helpful to provide a brief outline (backed up by your article headers) describing the content of your article.

Why Are You An Expert?

Briefly describe your experiences that led you to writing this article. What problem were you trying to solve? If applicable, you may also want to briefly describe your non-programming related knowledge that led you to write this article.

What Did You Learn?

Describe what you learned in the process of solving whatever problem your article solves. Sometimes this can be quite different but just as valuable as the content of your article itself.

What Can I Learn?

This isn抰 necessarily just a rehash of 搘hat is your subject matter? You can go into further detail here, describing what technologies, tools, and other special solutions you used. For example, many articles have gems of knowledge in them. For example, if I see an article on diagramming a database model in Visio, I might not care at all about databases but I might be interested in your Visio interface, while another person might not care about Visio but want to see how you extracted a database schema.

So, the 搘hat can I learn?section is really asking you to think about other interesting things that your article illustrates. If you write about these interesting things, chances are they will show up as a hit on Google, and you抣l be famous, if just for a moment.

The Article Itself

Enough said梖ormatting, spelling, code examples, etc.

Revision History

I see several of the more 損rofessional?writers put this in. When I see an article has been updated and I抦 interested in it, I immediately scroll to the bottom (although some people kindly put this header right at the top of the article) and check for a revision history. This tells me what changes the author has made梔ifferent pictures, changes in the article抯 content, adding new features or fixing bugs. The latter two should be accompanied with a code revision, which is very important if I am actually using the author抯 code.

A Conclusion

Here抯 your chance to really freeform it. What additional information do you have that didn抰 fit anywhere else? Are you going to continue working on your topic? Maybe a sneak peek at what you抮e thinking about writing next. What sort of feedback interests you?

Advanced Advice

In this section I have collated some of the suggestions made by others in the posts attached to this article. Once you feel competent at the basics, you might try out some of these suggestions as well. Yes, they require even more time committment on your part, but the benefits are many. You may learn something along the way (for example, when researching to see if anyone else has written something on your topic), you may improve your visibility (by choosing good keywords), and you may become more adept at communicating.

Keywords

Member ".S.Rod." suggested:

Regardless of whether or not an article is well written, I am more concerned about how easily helpful source code from articles gets reached with a simple keyword in the search engine (may be two sometimes).

This brings up an important point--choose your keywords well so that when someone is searching Code Project for information on the topic that you have written about, it will be more likely that your article will come up in the list.

Do Some Homework

Member Rohit Sinha wrote:

Check to see if the topic has already been covered. If it has, what does your article offer over and above the others? Does it approach the problem in a different way? Does it offer an alternative solution? It'll be good to mention the other articles too, and offer an explanation of why you thought yours was necessary. A hint should also be provided in the article description that accompanies the article title. After all, if there are 10 articles on a hover button, which one should I read?

This is excellent advice.

Code vs. Text

On this subject, I'm going to add my own response to the points of several readers, that they are more interested in the code than the text. I realize this will be controversial, but controversial is good. It makes people think.

If you can't express yourself in coherent, thoughtful, intelligent way using oral or written language, I'm going to find it really hard to believe that your code is going to do better. We translate concepts, expressed in language, into code. Not the other way around. Therefore, if the concept can't be expressed well in a language, I fail to see how it can be implemented well in code. This comes from personal experience. When I was 18, I couldn't express concepts very well. I worked for a guy that hammered it into me that I really need to learn how to express my concepts first, otherwise I'll write pathetic code. I really took that lesson to heart. Now, going back to the issue of English as a second language, I have no problem with poor grammar. However, it is pretty easy to figure out whether the person could have expressed his/her thoughts in his/her native language well, and the problem is simply a language barrier.

To reiterate, an article in which the text is poorly written (compensating for non-English fluent writers, of course) is an indication that the code will be equally, or even more, incoherent.

A Word About Ratings

You may think that I am orienting this article around getting good ratings. This is not the case. A high rating is merely a 搒ide effect?to a good article. At least, it usually works that way. One can also get obsessive about ratings. This isn't the point. If you have done your best, then whatever rating you get should be happily ignored.

Tools

This should probably go at the beginning of this article, not the end:

As mentioned above, for testing your article and program in different screen resolutions:
http://www.codeproject.com/tools/windowsizer.asp[^]

An excellent tool for writing an article is (I'm using it right now):
http://www.codeproject.com/jscript/cparticlewriterhelper.asp[^]

Conclusion

I wrote this article mainly out of frustration in seeing some of the articles that have recently been submitted. I would like to view this article as a "call to arms" to raise the bar of professionalism in our community--out of respect for each other. I realize that many people will disagree with what I have said. Well, good! The point is not whether you agree or disagree, but whether, as a result of reading this article and thinking about it, you see something in your own writing style that can be improved, however small.

Revision History

12-15-2002: First revision. Incorporated readers comments: fleshed out several concepts, added a few sections, and sanitized some of the more blunt statements (sorry Bill, I guess I removed some of my personality from the article).
12-14-2002: Original article