Why Write An Article?
Motivation to write a decent article is an important factor. This section discusses possible motivations.
Root Admin 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 RootAdmin "regulars" frequenting the help forums.
Root Admin 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 Root Admin.
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
click on 'My Settings' and enter your name. Your articles will be automatically updated.
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 Root Admin 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 - certainly, 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 member to experts far and above my own
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 Root Admin and are motivated to
write something themselves to contribute back to the community. Nice and
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 Root Admin 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
- 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
- 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
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
if you want help polishing your article, you can request that a mentor review
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.)
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
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.
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.
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 and the 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.
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 a particular background to the topic 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.
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.
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 the Reader Learn?
This isn't 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.
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. Root Admin has a lovely revision
history feature (viewable by click on the "Revisions" link on the left sidebar).
However, having an annotated description of your revisions is immensely
helpful. By the way, can you spot the spelling error in the author's
Here's your chance to really freeform 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
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 Root Admin 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 Root Admin 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 Root
Admin 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
- Desktop Development
- Web Development
- Mobile Development
- Cloud Computing
- Enterprise Systems
- 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 what section 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.
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.
I used the main points of my article to come up with the one line
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 targetting?
- 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 Root Admin'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
because of any fault of Root Admin but because writing a medium or large
article in an online format just isn't the best way to go about it. That
said, the submission wizard has been improved tremendously, in that you can save
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.
- I work is that I first write the article in an HTML editor (converting
from something like Word is also a PITA, so I don't recommend it.)
- 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.
- The WYSIWYG editor does not do spell checking, which is why I prefer to
work with an editor that does. If you are using the WYSIWIG editor, I
would suggest copying your article into an editor that does, and fix any
- I also go through the article and highlight all in-line code and the
click on the "var" clickey in the toolbar so that code words use the correct
- 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 Root Admin 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.
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 Root
Admin 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
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
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 your a masochist like me, I would suggest giving your images useful
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 it in a new window.
- Clicking on the red "X" will delete it
- Clicking on the little "pencil on paper" icon will allow you to edit it.
See all those lines where the resolution is in red? That's because Root
Admin thinks that those image files are too big (usually too wide, I'm not
sure if there's a horizontal 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 you're
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 click
on the "HTML" clickey in the toolbar, I can see my image:
Note that what I usually do (this based on the old way of working with
images) is put my images in a subfolder of the article's HTML. This means
I have "src" lines like this:
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
Additional Important Options
To the right of where you type in your article's title are some important
Here you can choose:
- The license that you prefer (read about the license options).
- Options on the status of your article (the Root Admin editors may also
set the status)
- Whether this is an article, video, or tip/trick
- Who can edit your article (admins, editors, or Root Admin members at
- 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
- 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!)
For testing your article and program in different screen resolutions:
An excellent tool for writing an article is (I'm using it right now):
Automatic table of contents generator (generated this articles TOC!)
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!
- Basically, a complete rewrite
- Added a reference to a great table of contents generator to the tools section
- Formatted the article to better comply with my own guidelines!
- Some additional recommendations that Chris Maunder suggested. " />
- 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).