Contents
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.
This article covers the Why? and How? of writing an article. For the technical specifications and policies please see the submission guidelines. These guidelines are brief and explain how to package up the article, what you need to add, and how you actually go about posting the article.
Motivation to write a decent article is an important factor. This section discusses possible motivations.
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 Marc Clifton on Google reveals two articles Ive written as the second and third hits (the first being Anglo Church Planting Strategist--huh?)
When submitting an article think carefully about your display name. 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. To change the displayed author name on your articles just login to CodeProject, hit 'My Settings' and enter your name. Your articles will be automatically updated.
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 ooh 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 expert can, loosely defined, simply mean providing expertise to someone else, no matter how simplistic the subject matter.
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.
I can really think of only one answer, since Im 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.
There are only a few things that make an article decent and separate it from the rest of the pack. The first is visual presentation, or formatting. The second is spelling, grammar and general readability (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.
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.
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 articles 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.
Also: please make sure graphics are less than 600 pixels wide. This ensures your article will fit within the confines of a page.
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
< - the '<' character
> - 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.
One of the guidelines for code formatting is that the code should be readable without horizontal scrolling on an 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 sufficepresent only the code that is core to your point. Secondly, if a block of code takes up more than a screen, well, its 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.)
Don't even bother. The syntax highlighting scripts strip out code colouring you do. The editors will strip out anything else. The goal of an article is to be readable and the more colors, underlines, bold tags, UPPERCASE SENTENCES, etc. that you add the more unreadable an article becomes. Keep it simple and keep it in tune with other articles on CodeProject so that readers don't have to mentally change gears each time they view an article.
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, ask 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, Jrgen 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 programmer, your article might actually get read. Does this seem like a harsh statement? Good!
Lets face it. Programmers are not technical writers. A spell checker cannot tell you whether youve written a decent sentence. To address this, Im going to fall back on my Dale Carnegie training and suggest a few guidelines (while deviating considerably from Mr. Carnegie). These guidelines arent 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.
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. If there is a particular background to the topic then a brief overview would be valuable to your readers.
(Or are you sharing what you just learned?)
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.
Many authors write articles because they wish to share something they themselves just learned. This is great - and is the very spirit behind CodeProject. However: remember that since you are a beginner you may make a mistake. Take care to check your work, and once your article is posted be ready to accept suggestions and improvements. Your article will be better for it, and there is no better way to 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.
This isnt necessarily just a rehash of what 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 what 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 youll be famous, if just for a moment.
Enough saidformatting, spelling, code examples, etc.
I see several of the more professional writers put this in. When I see an article has been updated and Im 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 madedifferent pictures, changes in the articles 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 authors code.
Heres your chance to really freeform it. What additional information do you have that didnt fit anywhere else? Are you going to continue working on your topic? Maybe a sneak peek at what youre thinking about writing next. What sort of feedback interests you?
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.
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.
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.
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.
You may think that I am orienting this article around getting good ratings. This is not the case. A high rating is merely a side 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.
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[^ ]
Automatic table of contents generator (generated this articles TOC!)
http://www.codeproject.com/csharp/htmlcb.asp
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.
08-16-2003:
- Added a reference to a great table of contents generator to the tools section
- Formatted the article to better comply with my own guidelines!
07-19-2003:
- Some additional recommendations that Chris Maunder suggested. :)
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:
