Why Write An Article?
Motivation to write a decent article is an important factor. This section discusses possible motivations.
Visibility
Code Project has high visibility in the programming world. It has a
constantly growing member and article base and the forums have a high amount of
traffic with Code Project "regulars" frequenting the help forums. Code Project has a high hit rate when doing a keyword search on many programming terms using
any of the popular search engines. If you are writing an article that
solves a problem or demonstrates how to use a particular piece of technology,
then in it is quite likely that your article will show up when people search for
solutions / examples. It's also a great way to find work--personally, I've
landed several multi-year contracts as a result of my visibility on Code
Project.
When submitting an article, think carefully about your display name. Sure, you can hide behind an alias, but
if you want to call attention to your articles (and perhaps your article
awards!) then you might to consider using your real name or some abbreviation of
your name, so that a potential employer gets some assurance that you are
actually referencing articles and awards that you actually wrote / won. Most likely, your motivation for writing an article has nothing to do with your 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 Code Project,
click on 'My Settings' and enter your name. Your articles will be automatically updated.
Peer Review
One of the things that I enjoy about writing an article is the peer review.
There are a lot of smart people that hang out on Code Project and over the years
I've found the comments of people to be incredibly helpful - they point out
where I've made mistakes, where I could have done things better, or just point
out a different approach. It would be difficult to find a world-class
community like this anywhere else - as a consultant, I am usually
hired because I am considered the expert, and it is nice to have access to a
community where I consider many of the members to be experts far and above my own
skills.
Giving Something to the Community
It's a very simple concept, but one that I have heard from other members --
they receive a lot of good information from Code Project and are motivated to
write something themselves to contribute back to the community. Nice and
simple!
Whatever the Reason...
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 degree, shedding some expertise on a
subject. With a readerships probably in the millions (nowadays I see Code
Project articles referenced everywhere) one just can't predict why someone lands
on your article -- perhaps the topic is something that they need to learn about,
perhaps they are looking for a code snippet that provides a usage example,
perhaps they are just perusing topics to which they have no familiarity.
Regardless, your article is visible, and it can only be in your best
interest to write a good one.
What Makes a Decent Article?
Here are a few pointers for creating a decent article - one that will hopefully
pass the muster of the unknown reader's criticisms:
- Well thought out - present your ideas with a concise and well thought
out plan. I often write an outline first, then flesh out the details,
revise the outline, and then fill in the text.
- Visually appealing - a liberal sprinkling of screenshots, flowcharts,
UML diagrams, etc., provide a nice visual "break" to the reader. Use
images:
- to show intermediate progress as well as the final result
- if applicable, to illustrate your architecture
- to illustrate complicated concepts, such as flow, schema, state,
messaging, interconnectivity, and so forth. A picture is worth a
thousand words!
- Spelling, grammar, and readability
- In this day and age, there's simply no excuse to not spell check
your article, especially with the number of free editors and spell
checkers out there. Ironically, even though I use a spell checker,
spelling mistakes always seem to slip through, especially words like
"for" vs. "four", and so forth. It's hard to catch those!
- Grammar can be harder, especially if you are not a native English
speaker. Consider asking another esteemed member to review your
article for you.
Use the Article Template Content Suggestions
When you use the article submission wizard, a boilerplate list of sections is
provided for you to fill in.
Personally, I always write the article first before using the article
submission wizard, but if this is your first time, use the headings in the
template if they are appropriate and you need help thinking of what the content
should be.
A word about "brief description" - a good article can be short and sweet
(though you might fall into the criticism of it looking more like a blog entry
at that point) or they can be tomes where you need to describe the details of
several technologies to paint the complete picture, or they can be somewhere in
the middle. If you are going to write a tome, I suggest you consider using
a table of contents generator to help your reader navigate and select topics to
read--see the Tools section at the end of this article.
Ask a Mentor
As explained
here,
if you want help polishing your article, you can request that a mentor review
your article.
Formatting Graphics
Graphics should illustrate only the necessary amount of information - crop
your image so that it contains only that which is pertinent in supplementing the
text - we don't need to see your taskbar, desktop background, etc. If you
have a very large image, consider a smaller thumbnail or a small fragment of the
image along with a link with text like "Click here for a full-size image" that
the reader can click on to view the image in its entirety at 100% a zoom level.
Flow of Ideas
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.
If your article is longer than a few screens of scrolling, consider creating a
table of contents (see Tools below.)
Focus
I tend to write articles on topics where I could probably write an entire
book on the subject. If you're faced with that situation, consider writing
an outline first to focus, like a laser beam, on specific concepts that you want
to write about. Stick with the plan!
Multi-part Articles
Another way to help your reader digest your articles is to break them apart
into several articles (this also brings up your article count, hahaha.) If
you are considering a multi-part article series, keep in mind that each
subsequent article in the series should:
- build on the work of the previous article
- represent a complete concept - whatever your article talks about should
be completed package in the current article.
The purpose of the second point above is to prevent people from writing
multi-part articles simply for the sake of doing so - there should be a clean
delineation of concepts in each part.
Formatting Text
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
&
- 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 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 (see Tools below.)
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:
- present only the code that is core to your point.
- if a block of code takes up more than a screen, consider organizing the
code into sections where you discuss the salient points of each section.
Colors and Formatting
The goal of an article is to be readable. Having more colors, underlines, bold tags,
SHOUTING, etc. can detract from the readability. You'll also want to
ensure a degree of consistency with other articles, so it is highly recommended that you don't stray too far outside of the lines of the Code Project style - don't invent your own header / sub-header color scheme, for example.
Some Further Ideas
The following are additional content ideas that come in part from Dale
Carnegie's How to Win Friends and Influence People and how to give a
2-minute talk. Keep in mind that these are just suggestions--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. If there is some specific background knowledge to the topic that you recommend the reader to have, then a brief overview would be valuable to your readers.
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. For example, if you are writing an article that solves some electrical engineering problem, describe your experience in that field.
Many authors write articles because they wish to share something they themselves just learned. This is great, and is the very spirit behind Code Project. If this is your first time writing an article, realize that while you may be an expert in what you are writing about, you may not yet have polished your writing skills. 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. Certainly, when I look back at my earlier work, I frequently roll my eyes at what I now consider to be a low quality of writing. I'm sure 10 years from now, I'll be doing the same when I look at the articles I'm writing today!
What Did You Learn?
Describe what you learned in the process of solving whatever problem your article solves. Sometimes this can be quite different than your original subject matter but just as valuable as the content of your article itself.
What Can the Reader Learn?
This isn't necessarily just a rehash describing your subject matter. You can go into further detail here, describing what technologies, tools, and other special solutions you used. Many articles have gems of knowledge in them. 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.
Revision History
Many authors will update their article from time to time, fixing bugs, adding
features, updating the content of the article itself. Consider putting in
a section on your revision history. Code Project has a lovely revision
history feature (viewable by click on the "Revisions" link on the left sidebar).
For example:
However, having an annotated description of your revisions is immensely
helpful. By the way, can you spot the spelling error in the author's
article title?
A Conclusion
Here's your chance to really free-form it. What additional information do you have that didn't fit anywhere else? Are you going to continue working on your topic? Maybe a sneak peek at what you're thinking about writing next. What sort of feedback interests you?
What were your experiences writing the code?
Some Additional Advice
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 tags 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.
There is a large list of tags to select from when you use the submission wizard:
Do Your 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.
Submitting an Article for Code Project to Post
If you are uncomfortable with submitting your article through the submission
wizard (discussed next), you can simply send your article (in zip form) to Code
Project from the main "Submit a new Article" screen:
Using the Submission Wizard
The submission wizard is an excellent editor that you can use to post your
article immediately, throwing it to the wolves, as it were.
Choose a Section and Subsection
This is a large list of section items, separated loosely into the following
categories:
- Desktop Development
- Web Development
- Mobile Development
- Cloud Computing
- Enterprise Systems
- Database
- Multimedia
- Languages
- Platforms, Frameworks & Libraries
- General Programming
- Graphic / Design
- Development Lifecycle
- General Reading
- Third Party Products
- Mentor Resources
This list can be daunting, and the subsections themselves can be many items.
It may also be confusing because your article might cover several reasonable
sections, such as "Multimedia", "Mobile Development", and "Database". My
advice is to think about the section in which your article fits best and to peruse the
subsections to see if that refines things a bit. When in doubt, leave a
comment for the editor in the "Comments for the editor" box:
which is immediately below the article WYSIWYG editor.
Article Title
After choosing a section and subsection, enter your article's title.
This should be the title of your article, which is different from a
one-line description. Sometimes it's easier to write a one sentence
description and then determine the title from that. If it helps, think
about the one line description as providing further detail about your title.
For example:
I used the main headers of my article to come up with the one line
description.
Tags
There are also a lot of tags to choose from. I would suggest first
checking off the technology boxes that apply directly to your article:
- What language(s) is it written in?
- What platform(s) is it targeting?
- What technologies are you demonstrating / depending on in your code?
- Who is the primary and secondary audience ?
Unless it is truly a beginner guide, the skill level should be Intermediate.
If you are Sacha,
it should always be Advanced.
The topics are a bit odd - it seems like a collection of keywords scraped
from articles before this incarnation of the article wizard. "Economics?"
"MOSS2007?" Really??? Leave this blank if you can't find a keyword
topic that fits!
One Line Description
The one line description appears on the front page of Code Project's article
listing, so it's important to be succinct to really capture the reader into
clicking on your article - you might consider the title to be the hook and the
one line description to be the line and sinker. If you are unfamiliar with
the idiom, read
here (isn't Wikipedia amazing?)
The Article Itself
The submission wizard provides a great inline editor:
That said, writing an article in the submission wizard is still a
PITA, not
because of any fault of Code Project but because writing a medium or large
article in an online format just isn't the best way to go about it. However, the submission wizard has been improved tremendously, in that you can save
drafts:
by clicking on the green "Save Draft" button, and you can then continue
editing your article later on by going back to the "Submit an Article" menu:
and then picking from any of the articles that you are currently editing:
The auto-save feature is also great, especially when a hurricane takes down
your Internet connection.
Suggested Process
This is what I do:
- I first write the article in an HTML editor (converting
from something like Word is also a PITA, so I don't recommend it.) The only formatting that I do is headers (starting at Header 2) and <pre> tags for code blocks. Sometimes I'll do <code> tags for in-text code elements, but I often leave that to the finishing process.
- I then click on the "HTML" clickey in the toolbar of the WYSIWYG editor
window, which takes me to the HTML
- I then paste my HTML into the window
- Then I click on the "HTML" clickey again to go back to the WYSIWYG mode,
so I can see what it looks like.
Cleanup
- The WYSIWYG editor does not do spell checking (though your browser might add this feature), which is why I prefer to
work with an editor that does. If you are using the WYSIWYG editor, I
would suggest copying your article into an editor that does, fix any
spelling errors, and paste it back.
- I also go through the article and highlight all in-line code and the
click on the "var" clickey in the toolbar so that in-text code words use the correct
style.
- I also check the width of my code blocks and force hard-returns to avoid
scrolling. This isn't that much of an issue anymore because Code
Project now uses snazzy horizontal and vertical scrolling code boxes if the
code is too lengthy in either width or height.
- Speaking of code blocks (those things between <pre> tags), go through
and select the correct language from the pulldown on the toolbar so that
syntax highlighting works correctly.
Legal Stuff
You are required to check the "I have read and agree to the contributor's
agreement", even if you haven't. But do read it--you are agreeing
to certain things such as that you are not plagiarizing, you own the rights to
the work being submitted, etc., and also that you are agreeing to give Code
Project certain rights with regards to your article, as well as giving rights
(based on the EULA that you select) to people who read and potentially use the
code in your article.
Are You Updating Your Article?
If you are updating your article, put in a one line description of what you
changed. This is valuable to the reader and appears in the revision
history:
Uploading Files
Use the "Add File" button to upload your source code and binaries (as a ZIP),
as well as any images or movies (JPG, GIF, PNG, SWF, FLV, MP4).
You can only select one file at a time, but the neat thing is, you are only
selecting the files. Once the files are selected, click on "Upload Files"
(hey Chris, the "F" should be capitalized in that button):
The great thing is, they all load in one
fell swoop.
Kudos to whoever realized that it is such a PITA to have to wait for each
image to upload, and that it is so much nicer to simply select all the images
and then upload them all together.
Unless you're a masochist like me, I would suggest using filenames for your images that are descriptive of those images.
Using Your Images
Once you've uploaded your images and files, you get this unsorted morass of
links in the Current Files section:
- Clicking on the file will open the file in a new window.
- Clicking on the red "X" will delete the file.
- Clicking on the little "pencil on paper" icon will allow you to edit the filename.
See all those lines where the resolution is in red? That's because Code
Project thinks that those image files are too big (usually too wide, I'm not
sure if there's a vertical restriction.) Ideally, you should pay
attention to this and resize the images to no more than 650 pixels wide.
Now here's the snazzy part:
Click on the "Insert/Modify Image" or, for a movie, "Insert/Modify Movie"
icon in the toolbar:
You will get a pop-up:
and all you do is type in the image/movie filename, click OK, and your image is inserted into the article:
Oops! Something went wrong! Maybe it's because I'm using Chrome
and/or I have something not working right on my machine. Anyways, by clicking on the "HTML" clickey twice (once to go into HTML view, the second time to exit HTML view mode) in the toolbar, I can see my image:
Note that what I usually do (this is based on the old way of working with
images) is to put my images in a subfolder of the article's HTML. This means
I have "src" lines like this:
src="WhyWriteAnArticle/whywrite23.png"
A quick search&replace to strip off the subfolder name fixes this before I
paste the HTML, and I almost never end up using the "insert image" feature
directly.
Additional Important Options
To the right of where you type in your article's title are some important
options:
Here you can choose:
- The license that you prefer (read about the license options, this is where you determine how others use your code.)
- Options on the status of your article (the Code Project editors may also
set the status.)
- Whether this is an article, video, or tip/trick.
- Who can edit your article (admins, editors, or Code Project members at
different levels.)
- Whether you want to mark the article as updated - IMPORTANT: uncheck
this if this is the first iteration of your article. If you don't do
this, your article will appear on the front page as "Updated" rather than
"New".
- Whether you want to hold off on publishing your article because you are
still working on it.
- And finally, whether you don't want HTML formatting stripped.
Typically, this should be left unchecked.
The WYSIWYG Editor is not Perfect
Keep in mind that the editor is not perfect - I frequently have to pop into
the HTML view of the article to fix some weird formatting thing that occurred
when inserting an image. Sometimes the way the carat behaves is bizarre
and makes it difficult to delete/insert text at the point where I want--again,
popping into the HTML view and fixing the problem there solves the issue.
Preview and Submit!
Although the WYSIWYG editor is
the cat's meow, you
should preview your article to verify the final way it will appear when
published. Of course, you can always edit it to fix up problems once
submitted (and I quite frequently do!)
Tools
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
Conclusion
It's interesting to read the conclusion that I wrote more than 9 years ago:
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.
Since then, I've grown older and it seems more moderate, as I ended up re-writing most of the rhetoric that existed in the previous incarnation of this work. My, how we change over time! And the article submission wizard has similarly undergone a great number of improvements over the years as well!
Hopefully, new and veteran authors will find something useful here!
Revision History
11-07-2012:
- Basically, a complete rewrite
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: