You have something to share. Now what do you do?
Do you have a piece of code, a tip, an article, or something else that you believe others would find useful? The following information will show you how you can share your items with everyone coming to CodeGuru. Our assumption is that your item will be presented as part of an article. This page will give you the specific details for entering an article using our online system.
We would rather get submissions than scare you off. If you have a question, doubt, or suggestion, thencontact us (email@example.com). There is a lot of information in the following guidelines. Most is common sense. If in doubt on a guideline, do your best and submit your article anyway! If there is an issue, we will contact you.
These guidelines are broken into the following sections. You can jump to any of these sections to get help.
- Submission Types
- Using the Online System
- The My Articles Page
- Quick Guide to Writing Articles
- Source Code Guidelines
- Documentation Guidelines
- Tips for Entering Articles
- Bug Fixes, and So Forth
- Naming Download Files
- Submitting Your Article by E-Mail
- Graphical Badges
There are four primary types of content on CodeGuru that you can submit. These are:
- Video Articles
- Book Reviews
Almost all of the submissions to CodeGuru are regular articles. Odds are your submission is also an article. The basic definition of an article submission is simply a piece of code or technique, along with a written explanation of it, that helps out another programmer. To that extent, there are three basic types of article submissions:
- Techniques—These are usually very small articles that simply relay a cool technique or means of accomplishing something. An example would be a simple technique shown to capture the user right-clicking on the header control of a listview.
- Derived Class(es)—This is when someone has extended a standard Visual C++/MFC class or provided a much-needed wrapper for a function or set of functions. A good example of this would be the various classes that extend the standard MFC classes such as CListCtrl, CTreeCtrl, and so on.
- Tutorials—Our personal favorite, these are articles that usually contain between 500 and 2,000 words and teach a given concept, programming technique, or technology. Tutorials can be beginner level or very advanced, depending on the topic and the intended audience. An example of a tutorial article would be "Beginner-level Tutorial on XML." Tutorials are generally the most popular items on any developer Web site and in a recent CodeGuru poll, the number one improvement most readers wanted was more tutorials.
Before writing and/or submitting a tutorial, please check the site to verify that there is not a tutorial already available for the topic.
- Tools & Frameworks—Another favorite of ours, this is an article that presents an entire application or framework that makes working with a given technology easier. The article can explain how the technology is being used and what benefits can be derived (faster development time, better UI, extended functionality, and so forth) from using the tool. A "tool" example might be an article that explains how to use DTDs with XML and then presents an application that allows for the visual definition and cataloguing of DTDs for a large programming team.
Video articles allow you to submit a video as the key element of your article. We can currently accept a number of video formats, but prefer AVI or WMV formats. There are a number of additional guidelines for video articles. Most of these are to insure a minimum quality of production as well as to ensure the content fits within the video format. Because the format of video articles is different from a standard article, there are separate guidelines for them located HERE (www.codeguru.com/video-guidelines.php). The video guidelines include information on software you can use to capture a video as well as how to submit the larger video files to be published.
For video articles, you should also review the general article guidelines presented in this document as well.
In addition to the standard articles mentioned above, CodeGuru also publishes book reviews on Developer-related books. In fact, CodeGuru has a section that focuses specifically on book reviews. Because the format of book reviews is different from a standard article, there are separate guidelines for them. The book review guidelines are located HERE (www.codeguru.com/review-guidelines.php).
Visual Basic Resources are also a part of the site. These categorized resources are links to third-party tools, add-ins, samples, articles, and more. These resources are generally not stored on the CodeGuru.com site and generally do not include code. Rather, these are links to the resources.
When linking your resource to the site, you should make sure you are placing it in the most appropriate category. Additionally, because you are providing a link to your resource, you should make sure that resource is on a page that will continue to exist.
Resources should only be linked into one category. Links are approved before going live on the site. Posting a resource to multiple categorizes is considered SPAM and will be treated as such.
You most likely got to this page because you selected a help button on one of the pages for submitting an article. The following sections will explain the process for entering an article as well as detail what each entry item does or is expecting. If you have trouble, you can always submit your article via e-mail; however, you may lose some of the benefits of using the online system.
Benefits of the Online System
By signing in and using the online system, you will be able to manage the articles you submit to CodeGuru. The online system enables you to enter articles in a "working" area. Once you are happy with an article in your "working" area, you can submit the article to be reviewed. Once you submit the article for review, it will become "pending" until a moderator reviews it. The moderator approves your article for posting. At any time, you will be able to see the status of your articles—working, pending review, or posted. Additionally, you will be able to access your articles to make updates that then can be resubmitted as an update.
As a registered user, any articles you submit will be accessible through the My Articles link that is within your profile page. When you start working on a new article, it too will be added to your My Articles page.
There are two primary pages used for submitting articles. On the first page, you provide descriptive information for your article including a title, the environment, and a short description. The description becomes the "lead" that appears on the CodeGuru home page when the article is newly posted. The following figure shows the form used for the first page.
Figure 1: Add title, lead-in and environments in this section.
On this portion of the page, you should enter the following information:
- Title—This is the title for your article. Keep it concise, yet descriptive.
- Subtitle (optional)—This is a subtitle if needed. Generally, you won't enter this.
- Environment (optional)—This is environment information relative to your article. Enter platforms, programs, languages, and other information into this area. Good information to enter includes the programming language (for example, C++, VB, VC++, C#), the platform (such as Win32, .NET, Windows 9x, unix), and version information for the language or platform). Examples include:
- VC++ 6.0, Win9x, WinNT
- VB 6.0
- C++, Win32
- C#, .NET Framework 1.1
Our suggestions for specific values you can enter:
- Platforms: Win 9x, Win32, WinNT, Win2k, Win2003, Linux, Unix, .NET 1.0, .NET 1.1, Mono
- Languages: VB, C++, VC++, VC++.NET, C#, VB.NET, Java, J#
- Other: MFC, STL, ANSI, Version numbers
- Summary—This is a very short description of your submission. This is the one or two sentences that are displayed on the site to describe your submission. As such, you should focus on the key information you are presenting: What will the reader learn from your submission?
Scroll down and you'll see the articles section area. Here you will choose what area of the site your content fits into. For example if you article was about ASP.NET, you would choose the .NET/C# topic from the site section dropdown and then choose the appropriate ASP.NET section from the categories section. You can double-click your selection or press the arrow image. Your choices will then show up in the selected categories section.
Figure 2: Shows the area where you choose what categories your content will appear on the site.
- Site Sections Dropdown:—This contains choices for the primary area where you will place your article. Selecting a value in this list box will fill in the selections in the following list box. You should be aware that these choices follow the topic areas listed in the navigation menu at the top of the page.
- Categories...—This selection is filled based on what you choose in the Site Sections list. Click on an option to add it to the Selected Categories list. You can select more than one area to place your article. Additionally, you can change the Site Section and select additional areas as well. We recommend that you don't select more than three or four areas to place your article.
- Selected Categories—Items are added to this list based on what you selected for categories. You can remove an item by simply clicking on the X. Be aware that if you select too many options, they will scroll out of view in this list box. The moderators and site editors will review your selection and, if it makes sense, they will choose additional areas to post your article as well.
Add tags/keywords to your articles so users can find your content. This also helps your content be picked up by the search engines. Simply type your tag/keyword into the textarea and click the arrow to add it to your article. It will then show up next to the "Assigned Tags" text.
Figure 3: Add tags/keywords to help readers find your content.
Body of Article—This is where you enter your article. You will enter your article as well as HTML mark-up to format your article. Add your article text and HTML mark-up in the body text area
Note: Add the image names including the brackets where you want your images to appear in your article body.
Example 1: This is the code needed to add images to your article
By default, there will be one page to your article. If your article is more than one page simply click the button to add an additional page.
You can toggle back and forth between the different pages of your article by clicking on the page tabs
Figure 4: This is the area where the text of your article will appear.
Article Images—You can add images to your article but first you have to save your work. Simply click the "Save" button at the bottom of the page. Your images must be in JPG, GIF or PNG format; otherwise, they will not be loaded into the system with your article. This can be done by using the "Article Images Management" area. Click on the "Upload Image" button and browse to your local drives to where you images are stored. Once you have chosen your image click open in the dialog box and your image will be uploaded.
Figure 5: Upload your images using the Articles Image Management Section.
You can remove unwanted images by clicking on the X next to the file.
Note: Add the image names including the brackets where you want your images to appear in your article body.
Example 1: This is the code needed to add images to your article </p>
Use this section to add your articles accompanying code. All code must be in the zipped format. Simply browse to your zip file, select it and it will be uploaded automatically. This zip file will appear at the bottom of each page of your article.
Figure 6: Upload your files using the Article File Management Section.
You can remove the file by clicking on the X next to the file.
Figure 7: Leave your comments to the CodeGuru Staff.
The bottom of the form for entering articles contains a PREVIEW button. You can click this button to get a preview of what your article will look like. Before you click this button, you should save any changes to your article by selecting the SAVE button under the article entry form. Clicking the PREVIEW button will open your article in a new window. You'll see how it will look when it is published. It is strongly recommended that you preview your article, especially to ensure that your figures and downloadables are available. You can close this window and go back to editing your article if additional changes are required.
You must save your article. Simply push the "Save" button and you're almost done.
Figure 7: Save your work!
Finally, when you have entered and saved your article, you then can submit it. You submit your article by clicking the "SUBMIT FOR POSTING" button at the bottom of the form. Once you click this button, your article will be put into the queue for the Moderators to review and accept it. A message will be displayed stating that your article has been submitted.
The My articles page can be accessed from your profile page or from the second page of the article submissions. The My Articles page looks similar to the following figure.
Figure 6: All of your articles appear here.
The My Articles page will list the status of any articles you have submitted. Published articles are listed at the top, submitted articles (Pending) are listed next, and articles that you have not submitted are listed last (Working). You should note that if you choose to edit a Pending article, it will need to be resubmitted.
This is a "Quick Guide" for article submissions. Please make sure your submission adheres to these guides before submitting.
- Is the documentation sufficient to help someone else use your code?
- Do your code samples compile and run?
- Have you removed all unnecessary files (*.opt, *.ncb, *.obj, *.aps) files from the ZIP? Submissions over 300 Kb will, in most cases, be rejected. Keep zips and images small!
- Has the article already been covered at CodeGuru? If yes, then why is yours better?
- If the article is an extension of an article, have you tried contacting the original author to produce a single article? Have you thought about posting it as a "Comment" to the original article? Simple mods to existing articles will not be accepted as a new article.
- We want quality of articles, not quantity.
First and foremost, we need some documentation . This doesn't have to be anything fancy, though we don't mind if it is, but if you think about answering the following questions, you should be off to a good start. I'd like to think that these are fairly obvious, but this has proven not to be the case!
- What does the code do?
- How do I integrate it with my existing code or how do I use it?
- If there already is a similar article on CodeGuru, how does this one differ? Why would someone want to use your version?
- Is there some aspect of the code that is of particular interest that perhaps wasn't covered in the documentation?
- What version of software was this code built with? This may be fairly obvious, but given the inevitable upgrade pace set by software companies, this may not remain so obvious.
The idea is to give the reader a clear idea of the purpose of your code, instead of forcing them to download a project, build it, and then hunt around to find out what the sample does.
First and foremost, does the code actually work? We do sometimes get code that, for one reason or another, just does not work. Please check that the source code you send compiles cleanly, and if part of a larger demo application, that the application itself runs OK.
Sample Executable: If providing a sample executable, please make sure it is linked with the release libraries. The whole point of a demo executable is to give developers a quick intro to your code. If they have to recompile to get the application to run on their system, there is no use in supplying the executable in the first place. Second, try to be conservative about just how big a sample you upload; a 4 Mb sample just isn't going to interest a lot of people.
Sample Project: It is recommended that you also include a sample project. When creating a ZIP file for the sample project, please do not include either the Debug or the Release directories. They simply inflate the size of the ZIP file. Also, do not include the *.clw, *.ncb, *.opt and other such files that are automatically recreated.
Style: We cannot (and will not) dictate coding style, but we do ask that the general coding guidelines be adhered to so that other programmers can understand your code easily. A few other things that you may want to consider when preparing a article are:
- Does the code compile and run cleanly? Even under the highest warning level?
- It is okay to use others' code as a base as long as you make it totally clear that some/most of the code isn't yours, and keep all copyright notices in the original code. If you use someone else's code, DO NOT remove their copyright notices. There is a lot of code reuse here; that's the point, after all. As far as the articles that are being posted here go, we expect to see credit where credit's due, both in the code and the HTML as appropriate.
While we are talking about copyrights, you retain copyright of your article and code, but by submitting it to CodeGuru you give permission to use it in a fair manner and also permit all developers to freely use the code in their own applications— even if they are commercial .
File naming convention: If your contribution includes files that will be downloaded by your readers, then to make life easy for everyone, we ask that you follow these filename conventions:
|coolcode_src.ZIP||The zipped source code for your article|
|coolcode_demo.ZIP||The zipped demo project for your article|
In place of coolcode, use a name that describes your article's topic and thus the contents of the download files.
Tips for Entering Articles
You need to use HTML markup when entering your articles. You should use simple HTML. Programs such as Microsoft Word create complex HTML that uses style sheets and should be avoided if possible. For tutorials on HTML, check out HMTLGoodies.com.
The following are a few basic suggestions. You can actually format everything in a basic article with just these suggestions:
- If your article has headings, use <H3>level and lower.
- Wrap paragraphs with <P>tags.
- Use <BR>for a line break.
- Use <PRE> tags to wrap your code. The <PRE> tag will retain formatting without the need for additional HTML tags. <STRONG> or <B> tag) as well as italics (<EM> or <I> tags)
- Don't use tabs in your code. Use three spaces instead of a tab.
- Limit lines of code to 65 characters. You may, of course, use your language's internal line-breaking protocols, such as adding a space and an underscore in Basic languages.
- If you include images, try to keep their file size small. 20 to 30 Kb per image is okay. 300,000 Kb per image is too big. The bigger the image file, the longer it will take to view your article.
We get a number of modifications to existing posts, which can be a good thing. In these cases, can we ask that you first attempt to contact the original author and then try to liaise with him/her to produce an update to the original article? This way, we can retain continuity with the original article as well as reducing the number of completely new pages that need to be posted.
If you are updating your own article, you can do this through the My Articles interface in your profile. If you have trouble, you can contact us firstname.lastname@example.org. We are happy to help or to answer any questions. Please include the URL of the article.
Please send all your articles to email@example.com. If you are submitting a Visual Basic article, you also can send it to firstname.lastname@example.org. Java articles can be sent email@example.com. Your article then will be forwarded on to the person responsible for the section in which your article will be posted. Please refrain from posting articles directly to individuals unless they specifically ask you or are expecting an e-mail from you.
When e-mailing the article, you can help us out. If you believe you article neatly fits in one of the categories, please let us know. (Providing language, categories, and subcategories from the site is really appreciated.) A one- or two-sentence description for the index page is also appreciated. None of this is mandatory, but it really helps us! For example:
Subject: VC++ Article - Using Remoting Procedures with ADO.
Attached please find my files for the article "Using Remoting Procedures with ADO." This would fit in the ATL/COM section of the VC++ site.
A description of my article:
"ADO can be used across a network or the internet using Remoting. This article explains the details needed to implement this in just four easy steps."
- Anon E. Mouse, firstname.lastname@example.org
Your article should be sent as an attachment. Embedding your article in an e-mail message directly often does horrible things to the formatting.
If you do want to send an archive, please use a plain ZIP file rather than a self-extracting executable. Remember that if your project contains long file names, you ought to use an appropriately modern ZIP program to create the archive. InfoZip, WinZIP, and PK-Zip, to name a few products, all have programs that do this correctly.
Also, please send us your username or screen ID ( NOT your password). This facilitates our editors posting your article to your account. If you do not yet have an account with CodeGuru, please create one as soon as you e-mail your article and send the info email@example.com.
Of course, remember that you can always enter your articles online.
After you have been published on CodeGuru, you will want to let people know! To help you, we have provided the following graphical badges that you can use. If you have an article posted on the site, then you can use the following graphics provided you follow the rules in this section:
If you place this graphic on your site, you must link it back to CodeGuru.com. You can link it to either the home page (http://www.codeguru.com), to your profile page, or to your article. If you want to link it to a different CodeGuru page, ask us.
Just to cover us.... These badges cannot be changed in any way, nor can you use them in any way other than what we have specified here unless you obtain our written permission. We reserve the right to ask that these be removed at any time.
If you haven't published an article, you can still use the following badges provided you are a member (have a signin ID) or post to our forums.
- Member—You have registered with CodeGuru and have a sign-in name.
- Poster—You post in the CodeGuru discussion forums.
As you know, this site is a valuable resource for the developer community. Please note, however, that to avoid legal complications, we need to obtain your permission to use any computer code and any related materials ("resources") that you are providing to us. Accordingly, by submitting any such resource to CodeGuru, you grant to QuinStreet a nonexclusive, worldwide, perpetual license to reproduce, distribute, adapt, perform, display, and sublicense the submitted resource (in both object and source code formats, as well as on and off the Web), and you acknowledge that you have the authority to grant such rights to QuinStreet.
By submitting the resource, you also grant your article's readers the permission to use any source code in the resource for commercial or noncommercial software. PLEASE NOTE THAT YOU RETAIN OWNERSHIP OF ANY COPYRIGHTS IN ANY RESOURCES SUBMITTED!
ALSO, IN MAKING THE RESOURCE AVAILABLE TO OTHER SITE VISITORS FOR DOWNLOADING, QUINSTREET WILL INFORM SUCH OTHER VISITORS THAT, ALTHOUGH THEY MAY DOWNLOAD ANY RESOURCES FOR COMMERCIAL OR NONCOMMERCIAL USES, THEY MAY NOT REPUBLISH THE SOURCE CODE SO THAT IT IS ACCESSIBLE TO THE PUBLIC WITHOUT FIRST OBTAINING THE COPYRIGHT OWNER'S PERMISSION.
And finally, if you have questions on any of what is stated in these submission guidelines, you can send questions firstname.lastname@example.org.