Tip #1: What Every Mentor Should Know

Introduction

There are a few things you should and shouldn't do when dealing with first-time authors. The main thing to keep in mind is that you want to help them become better authors,

Show Respect

By definition, first-time authors won't know everything when it comes to CodeProject article formatting and how to interact with the CodeProject community, and especially how to deal with blunt comments from members. For the most part, your job will be to tell them, "Take a look at this, that's the way you should do it."

Just because the author doesn't have experience, doesn't mean he's stupid. He just lacks knowledge, and you can tell him what he needs to know, but in a polite, positive way. Example of the wrong way:

Get this steaming pile of horse manure off the site until you learn how to format it properly.

Example of the right way:

Your article looks like it could be very helpful. With a few formatting changes, it would look better and be easier to read.

The key points are: be polite and be positive.

After you write down some suggestions, take a moment to read them, and think how you would feel if you got these suggestions. There is a fine line being being critical and being negative, and what you don't want to happen is for the author to think you're insulting him, or being condescending.

How To Be a Great Writer

I have no idea how to do this; I don't think anybody does. What I do know is how to write an article that is readable and that will make other members want to read it:

Write as if you're talking to another programmer.

It's really that simple. When you talk to another programmer, you would say

"I had this idea for improving performance, so I wrote this code, and then I tried this test, and then I ..."

You don't have to be fancy, you just have to explain things clearly.

• Explain how you got the idea, what problem you're trying to solve
• Show some code snippets, explain what they do
• Explain how you approached the problem. What sites helped you? What references did you use?
• Explain how you designed and organized the code
• Include a demo app if possible. Everyone likes to look at screenshots.
• Don't forget to tell the reader how to use the code in his own app

It Doesn't Have To Be Perfect

Your advice to new authors should help them make their articles better, bit by bit. It's an incremental process; short of rewriting the entire article for them, you have to start by talking about some of the basic things first, like article formatting. Many first-time authors are not that familiar with HTML, and have never used the UL, OL, or LI HTML tags. What you might see is the author's attempt to roll his own bullet lists, which look bad and usually involve a lot more work than just using the standard HTML list tags. This is a good starting point, if you're trying to decide what to tell the author. Again, there are right ways and wrong ways to communicate this. Example of the wrong way:

Is this a joke? WTF were you thinking of? It looks like crap.

Example of the right way:

By using some standard HTML tags, you will save yourself a lot of work, and it would look better and be easier to read. Let me give you an example...

The key points are: be polite and be positive.

You don't want to scare the author by telling him he has a lot of work to do. What you should do is concentrate on the, say, top 5 problems that will allow him to present his ideas and code in a way that's readable and useful to other members.

Remember that just because CodeProject has a lot of really good articles, doesn't mean that the author has examined them in detail; he's probably very busy, just like you are. So another simple and obvious thing to tell an author is, Take a look at this article, this is how you want to do it.

Dealing With Members

Sooner or later an author will complain to you about some comment left by a member. The comment may be justified or not; that's not the point. The point is, it's made the author feel like he's been rode hard and put up wet. In general, there's probably nothing you can do about the comment, unless it involves some kind of bug report, in which case you should explain what the author has to do to fix the bug and re-post his article.

One of the hardest things an author has to get used to on CodeProject is the tone of posts, which as you know can be blunt, abrasive, insulting, or all three. You can do nothing about these and neither can the author; the sooner he learns that he will get some of these, the better. What you should do is tell the author to never respond in kind. He might get some momentary satisfaction, but he risks turning the article's forum into a mud bath. Tell the author that these posts will happen; no one can prevent them from being posted; that he should respond to all posts in a polite manner; and that if he can't respond politely, it's best not to respond at all.

Finally, tell the author that if the post is particularly vile, threatening, or racist, he can make a request in the Suggestions Forum, and the site admins will take care of it.

Dealing With Negative Posts

OK, so someone posts a rude, negative comment on the author's shiny new article. Believe me, I know what this feels like, I've gotten quite a few. They all have the same message, if not the words:

I didn't like this article. You don't know what you're talking about. I'm voting it a 1.

Unless the poster is just a troll, I make at least one attempt to find out what he's upset about. I write something like:

I'm sorry you didn't like the article. Can you tell me why you didn't like it? If you can give me some details, I will try to fix any problems.

Most of the time, this works wonders. The poster is astounded that I'm interested in his opinion, which is why he didn't bother to explain in the first place. Now he gives me some details, which I use to fix problems, or explain things better. As a plus, he might even give the article a better rating.

Dealing With Low Votes

This issue is another tough one for new authors. You have to emphasize the long-term view; over time, people will see that the article is useful, and will rate it higher. In the short term, articles are being read by people who don't necessarily need them right at the moment, and who rate an article accordingly.

You need to tell authors that over time, their articles will improve, as they get more experience. They can revise articles as they learn more, and posts on the article's forum will help them see how to improve the article. The author should take each post - even the negative ones - as an opportunity to improve his article. You can also suggest that the author read the posts made on other article forums, to see what he is likely to receive.

In Conclusion

It is hard for some first-time authors to understand why they should even bother, given the kinds of posts they get. The last thing I like to tell authors, after giving them some suggestions, is

I hope you will continue to improve this article.

It's always nice to be asked.