PDA

View Full Version : Informal Forum Posting Guidelines: Commentary



Alfonse Reinheart
05-29-2011, 11:47 AM
I'm working on a set of informal posting guidelines, and I have my first draft done. I'm interested in what you think and whether I've missed anything or if something is unclear.

The best way to get help in this forum is to ask your questions in a way that makes it easiest for us to give you help. Consider the following to be a series of informal guidelines for posting questions.

Before you ask questions of others, it is respectful to put forth some effort in solving the issue yourself. It is generally faster for you (if your question has already been answered) and it keeps down the number of redundant or simple questions the forums receive. To this end, you should do the following before asking a question:

1: The OpenGL Wiki (http://www.opengl.org/wiki/Main_Page) is a good source of information. Check the FAQ (http://www.opengl.org/wiki/FAQ), Common Problems (http://www.opengl.org/wiki/Common_Mistakes), and Getting Started (http://www.opengl.org/wiki/Getting_started) pages before posting, to see if your question is something that has been frequently asked and answered.

2: Google is your friend. Or Bing, if you prefer. Or whatever searching service you prefer; it doesn’t matter. It would be best for all involved if your question could not be answered via a simple search based on the terms you’re interested in.

3: Search the forum. The OpenGL forums have an extensive search function, and the forums have been around for years. It is very possible that your question has been asked and answered before. Make use of those search abilities before posting (but don’t post in the thread you find unless it is a recent thread).

4: This forum is an OpenGL forum, not a general coding forum. So try to focus your question(s) on OpenGL matters. Questions should be about the OpenGL API, issues around the API (WGL/GLX matters), shaders, or something directly related to those things. Questions generally about graphics matters related to OpenGL are fine. General graphics questions are also acceptable, though OpenGL should be involved at some point.

5: This is an OpenGL forum, not an OpenGL ES or WebGL forum. While ES is a similar specification to desktop OpenGL, it is not exactly the same. Forum users are more likely to be able to answer desktop OpenGL questions than ES questions. You can certainly ask questions about these things, but if you do, please state up-front that you are asking questions about ES or WebGL. Also, you are more likely to get ES (http://www.khronos.org/message_boards/viewforum.php?f=19&sid=a252f897090dfe0828f5da581f0 f91f8) or WebGL (http://www.khronos.org/message_boards/viewforum.php?f=34&sid=a252f897090dfe0828f5da581f0 f91f8) help by asking on the Khronos forums dedicated to those subjects.

6: Is your question about a homework assignment? If so, remember that the purpose of homework is to help you learn. It does you no good to be told the answer to a homework assignment. Also, this is cheating, which is generally frowned upon in academic institutions.

Posting Guidelines:

1: Use a clear thread title. A good thread title should be a very short summary of the problem. For example, if your problem seems to be with textures, then the word “texture” should be somewhere in the title. Titles probably should be 8 words or less, though more can be used when necessary.

There is also no need to use words like “please help” or “urgent” in your thread title. By posting in the forum, you are already asking for help; simply state what the problem is. And people will generally not quickly flock to your thread just because you claim that it is urgent.

2: Put your question in the correct forum area. There is a text description for what each forum area is for, so this should not be particularly difficult.

The platform-specific forums are not for users working on a particular platform. They are for issues related specifically to that platform. So you should not ask a question in the Windows forum just because you are developing a Windows application. Only ask there if you are having issues setting up an OpenGL window on Windows. If you are using FreeGLUT or a similar toolkit that abstracts platform dependent issues, then you probably should not be posting in a platform-specific forum.

The most vexing issue is probably the difference between the “Beginners” forum vs. the “Advanced” forum. The distinction is not simple, and generally you’ll get help in either one. A good rule of thumb is that if you don’t feel comfortable with OpenGL as a whole yet, then your question probably should go to “Beginners”.

3: Clearly state your problem in your text. Make sure to include all relevant details. If you have only written single paragraph, that’s probably not enough detail. A single sentence is completely out of the question. While overdoing the detail is possible, it’s better to put too much detail in than not enough detail.

Never just say “it doesn’t work;” that is almost never helpful, nor is writing a single sentence and posting a block of code. What you don’t want to do is engage in dueling dialog, where the first responder asks for clarification, you provide an additional detail, they ask for more clarification, and so on.

To this end, your post should include:
What the problem you’re having is. What the results you expect to see are. What you are actually seeing, and how it differs from what you expect to see.
Use pictures if it makes it easier to understand the issues around the problem. The more relevant information you provide (to a point), the more likely the forum users are to be able to solve your problem.

4: Supply all relevant information about your setup and system. This includes:
State your OS, graphics card, and driver version. At a minimum, include the results of glGetString for GL_VENDOR, GL_VERSION, and GL_RENDERER. State up front whether you are using shaders (if you don’t know, then you aren’t). If so, state what kind of shaders you are using (glslang, Cg, ARB assembly, etc), as well as version information about which version of shaders you are using. State if you are writing to core OpenGL 3.2 or above. State whether you are using a toolkit like GLUT, GLFW, etc. Also, stop using GLUT; use FreeGLUT instead.
5: Do not post in old threads. If your search on this site unearthed a thread with a similar question to yours, but that thread hasn’t been posted in for more than 6 months, resist the urge to post in that thread, no matter how appropriate it may seem. Simply make a new thread; it will decrease confusion for readers of the thread. If you need to refer back to the old one, post a link in your description.

6: Do not request private help. Specifically, do not ask a question openly in the forum, then provide your email address and tell people to mail you the answer.

The purpose of a discussion forum is to discuss things openly. This allows everyone to share in the discussion as well as allowing everyone to share in the results. By asking for private help, you are taking away from the forum without giving back. As you might imagine, this is quite impolite.

Something similar goes for private messages. Do not post a thread and then private message forum members as a way of advertising it.

Formatting your post:

Proper formatting is always a good idea. If someone can’t read your post, they can’t answer your question.

1: Avoid net-speak and use reasonable English. Common mistakes include:
Using “u” instead of “you”, or similar improper contractions. Not capitalizing the word “I” or the first letter of sentences. The use of multiple exclamation points or question marks at the end of a sentence. The use of ellipsis marks (...) instead of periods.
2: Paragraphs should have an empty line between them. Also, paragraphs should usually consist of more than one sentence. Putting each sentence on a paragraph is not necessary and makes the post difficult to read.

3: Word wrapping is automatic. You do not need to manually word wrap by pressing <enter> at the end of a line.

Posting source code:

It is perfectly fine to post source code. The important question is which code and how much to post. Knowing which code is relevant is not exactly easy when you don’t know how things work and what exactly is wrong. It’s a catch-22: if you post too much code, most people won’t bother sifting through it to find your problem. But if you don’t post enough code, then they’ll have to ask you to post more since the problem doesn’t appear to be in what you posted. You will have to use your own judgement to decide which source to post.

If you do post code, make sure to properly format it. Always use code tags. These tags look like this:
code goes here [/code ], except without the space between the ‘e’ and the ‘]’ of the tags. If the source code in question is long (more than a half-page or so), enclose the code tags in spoiler tags. This will create a small box that the user can press a button in to display the contents. Spoiler tags look like this: [spoiler ] stuff goes here.[/spoiler ]. Again, remove the spaces in the tags to make them work. Properly formatted code looks like this:

[CODE]
void some_func()
{
glDrawArrays(...);
}


Make sure that the source code is properly tab indented. You don’t need to use any particular indentation style, but you need to have some kind of indentation to make it easier to read. Just copy and paste it directly from your source files.

Users will generally assume your code is either C or C++. If it is not, then you should say so in the text preceding the source code.

If you are having trouble with shaders, post them as well. Make sure that the version of the shader language in question is clearly stated, either in the shader code with a #version statement or somewhere in your text.

kyle_
05-29-2011, 02:17 PM
Nice writeup.
Common sense pretty much, but I'm afraid that the target audience you want to get to the most is pretty much out of reach.

MZ
05-30-2011, 07:51 AM
Dear Alfonse Reinhart, a.k.a Korval.

Condescending tripe constitutes 80% of your text. The rest is half obvious, half valid mixed bad.

Had your "informal guideline" become what you are hoping it to become, it would be a slap in the face to any decent person you are trying to represent here.

The fact you clearly don't realise the above, makes you look kind of delusional. But even if we ignored the unacceptable form of your proposal, there is still the history of your disruptive behaviour in this forum to consider. You made recognisable name (2 names actually) with record post count by pestering other posters by and pumping volumes of pointless, irrelevant noise into focused technical discussions. And now you dare to come up with this condescending, wannabe stunt. This is batshit insane. You are in need of prescription from a doctor, not in need of writing prescriptions to others.

BionicBytes
05-30-2011, 08:05 AM
Blimey a little strong !
What ever your personal views of him the suggestion is sound. A great many number of posts are unreadable, incomplete or inacurrate. This can only help.
One absent point is that people should not cross-post.

Khronos_webmaster
05-30-2011, 08:39 AM
Hi Alfonse,

This is a great start to a long over due Posting Guideline, and your contribution is very much welcome. I think you have covered most of the issues we see from new members to the forums (along with BionicBytes 'cross posting' suggestion ).

MZ: from a moderators point of view, we deal with many of the issues raised in these Guidelines. Personally, I feel this will also help new comers better understand what they need to post in order to get the best help possible. Obviously you feel the Guile Lines can be improved upon, so we look forward to seeing some constructive feedback from you.

Alfonse, if you require more feedback from myself or the OpenGL ARB, please let us know. Once the text is finalized we can post this at the top of the forums page making it easy to find.

Board rules: Suggestions for the Board Rules, which a person is forced to view when they first create an account, are also welcome. A link to the posting guidelines from the board rules I think would be beneficial, as well as a link in the Welcome email.

Thanks, and well done!

Alfonse Reinheart
06-01-2011, 06:56 PM
Here's a revised version of the guidelines. I included links to the OpenGL man pages (all versions + GLSL), as well as mentioning cross posting as BionicBytes suggested. And it would be great to hear from the ARB and the webmaster on these.

The best way to get help in this forum is to ask your questions in a way that makes it easiest for us to give you help. Consider the following to be a series of informal guidelines for posting questions.

Before you ask questions of others, it is respectful to put forth some effort in solving the issue yourself. It is generally faster for you (if your question has already been answered) and it keeps down the number of redundant or simple questions the forums receive. To this end, you should do the following before asking a question:

1: There are many good sources of information on OpenGL available on the web. You should check these before posting.
There are reference pages available covering the OpenGL API. There are pages covering OpenGL versions 2.1 (http://www.opengl.org/sdk/docs/man/), 3.3 core (http://www.opengl.org/sdk/docs/man3/), and 4.1 core (http://www.opengl.org/sdk/docs/man4/), as well as GLSL (all versions) (http://www.opengl.org/sdk/docs/manglsl/). The OpenGL Wiki (http://www.opengl.org/wiki/Main_Page) is a good source of information. Pages of interest include the FAQ (http://www.opengl.org/wiki/FAQ), Common Problems (http://www.opengl.org/wiki/Common_Mistakes), and Getting Started (http://www.opengl.org/wiki/Getting_started) pages.
2: Google is your friend. Or Bing, if you prefer. Or whatever searching service you prefer; it doesn’t matter. It would be best for all involved if your question could not be answered via a simple search based on the terms you’re interested in.

3: Search the forum. The OpenGL forums have an extensive search function, and the forums have been around for years. It is very possible that your question has been asked and answered before. Make use of those search abilities before posting (but don’t post in the thread you find unless it is a recent thread).

4: This forum is an OpenGL forum, not a general coding forum. So try to focus your question(s) on OpenGL matters. Questions should be about the OpenGL API, issues around the API (WGL/GLX matters), shaders, or something directly related to those things. Questions generally about graphics matters related to OpenGL are fine. General graphics questions are also acceptable, though OpenGL should be involved at some point.

5: This is an OpenGL forum, not an OpenGL ES or WebGL forum. While ES is a similar specification to desktop OpenGL, it is not exactly the same. Forum users are more likely to be able to answer desktop OpenGL questions than ES questions. You can certainly ask questions about these things, but if you do, please state up-front that you are asking questions about ES or WebGL. Also, you are more likely to get ES (http://www.khronos.org/message_boards/viewforum.php?f=19&amp;sid=a252f897090dfe0828f5da581f0 f91f8) or WebGL (http://www.khronos.org/message_boards/viewforum.php?f=34&amp;sid=a252f897090dfe0828f5da581f0 f91f8) help by asking on the Khronos forums dedicated to those subjects.

6: Is your question about a homework assignment? If so, remember that the purpose of homework is to help you learn. It does you no good to be told the answer to a homework assignment. Also, this is cheating, which is generally frowned upon in academic institutions.

Posting Guidelines:

1: Use a clear thread title. A good thread title should be a very short summary of the problem. For example, if your problem seems to be with textures, then the word “texture” should be somewhere in the title. Titles probably should be 8 words or less, though more can be used when necessary.

There is also no need to use words like “please help” or “urgent” in your thread title. By posting in the forum, you are already asking for help; simply state what the problem is. And people will generally not quickly flock to your thread just because you claim that it is urgent.

2: Put your question in the correct forum area. There is a text description for what each forum area is for, so this should not be particularly difficult.

The platform-specific forums are not for users working on a particular platform. They are for issues related specifically to that platform. So you should not ask a question in the Windows forum just because you are developing a Windows application. Only ask there if you are having issues setting up an OpenGL window on Windows. If you are using FreeGLUT or a similar toolkit that abstracts platform dependent issues, then you probably should not be posting in a platform-specific forum.

The most vexing issue is probably the difference between the “Beginners” forum vs. the “Advanced” forum. The distinction is not simple, and generally you’ll get help in either one. A good rule of thumb is that if you don’t feel comfortable with OpenGL as a whole yet, then your question probably should go to “Beginners”.

3: Do not post the same thread in multiple forum areas. This is called "cross-posting," and is not necessary for you to get help. If you make a post in the wrong forum area, only post again in the right one if people have not already started to comment on your current one. Also, lack of comments is not a sign that you have posted in the wrong area, so there is no need to post in “Advanced” if you didn't get a response in “Beginners”.

4: Clearly state your problem in your text. Make sure to include all relevant details. If you have only written single paragraph, that’s probably not enough detail. A single sentence is completely out of the question. While overdoing the detail is possible, it’s better to put too much detail in than not enough detail.

Never just say “it doesn’t work;” that is almost never helpful, nor is writing a single sentence and posting a block of code. What you don’t want to do is engage in dueling dialog, where the first responder asks for clarification, you provide an additional detail, they ask for more clarification, and so on.

To this end, your post should include:
What the problem you’re having is. What the results you expect to see are. What you are actually seeing, and how it differs from what you expect to see.
Use pictures if it makes it easier to understand the issues around the problem. The more relevant information you provide (to a point), the more likely the forum users are to be able to solve your problem.

5: Supply all relevant information about your setup and system. This includes:
State your OS, graphics card, and driver version. At a minimum, include the results of glGetString for GL_VENDOR, GL_VERSION, and GL_RENDERER. State up front whether you are using shaders (if you don’t know, then you aren’t). If so, state what kind of shaders you are using (glslang, Cg, ARB assembly, etc), as well as version information about which version of shaders you are using. State if you are writing to core OpenGL 3.2 or above. State whether you are using a toolkit like GLUT, GLFW, etc. Also, stop using GLUT; use FreeGLUT instead.
6: Do not post in old threads. If your search on this site unearthed a thread with a similar question to yours, but that thread hasn’t been posted in for more than 6 months, resist the urge to post in that thread, no matter how appropriate it may seem. Simply make a new thread; it will decrease confusion for readers of the thread. If you need to refer back to the old one, post a link in your description.

7: Do not request private help. Specifically, do not ask a question openly in the forum, then provide your email address and tell people to mail you the answer.

The purpose of a discussion forum is to discuss things openly. This allows everyone to share in the discussion as well as allowing everyone to share in the results. By asking for private help, you are taking away from the forum without giving back. As you might imagine, this is quite impolite.

Something similar goes for private messages. Do not post a thread and then private message forum members as a way of advertising it.


Formatting your post:

Proper formatting is always a good idea. If someone can’t read your post, they can’t answer your question.

1: Avoid net-speak and use reasonable English. Common mistakes include:
Using “u” instead of “you”, or similar improper contractions. Not capitalizing the word “I” or the first letter of sentences. The use of multiple exclamation points or question marks at the end of a sentence. The use of ellipsis marks (...) instead of periods.
2: Paragraphs should have an empty line between them. Also, paragraphs should usually consist of more than one sentence. Putting each sentence on a paragraph is not necessary and makes the post difficult to read.

3: Word wrapping is automatic. You do not need to manually word wrap by pressing <enter> at the end of a line.

Posting source code:

It is perfectly fine to post source code. The important question is which code and how much to post. Knowing which code is relevant is not exactly easy when you don’t know how things work and what exactly is wrong. It’s a catch-22: if you post too much code, most people won’t bother sifting through it to find your problem. But if you don’t post enough code, then they’ll have to ask you to post more since the problem doesn’t appear to be in what you posted. You will have to use your own judgement to decide which source to post.

If you do post code, make sure to properly format it. Always use code tags. These tags look like this:
code goes here [/code ], except without the space between the ‘e’ and the ‘]’ of the tags. If the source code in question is long (more than a half-page or so), enclose the code tags in spoiler tags. This will create a small box that the user can press a button in to display the contents. Spoiler tags look like this: [spoiler ] stuff goes here.[/spoiler ]. Again, remove the spaces in the tags to make them work. Properly formatted code looks like this:

[CODE]
void some_func()
{
glDrawArrays(...);
}


Make sure that the source code is properly tab indented. You don’t need to use any particular indentation style, but you need to have some kind of indentation to make it easier to read. Just copy and paste it directly from your source files.

Users will generally assume your code is either C or C++. If it is not, then you should say so in the text preceding the source code.

If you are having trouble with shaders, post them as well. Make sure that the version of the shader language in question is clearly stated, either in the shader code with a #version statement or somewhere in your text.

Khronos_webmaster
06-02-2011, 06:53 AM
Hi Alfonse,

Posting Guidelines

Point 1 - 2nd Paragraph:

"There is also no need to use words like “please help” or “urgent” in your thread title. By posting in the forum, you are already asking for help; simply state what the problem is. And people will generally not quickly flock to your thread just because you claim that it is urgent."

Perhaps would be more clear as:

"There is also no need to use words like “please help” or “urgent” in your thread title. By posting in the forum, you are already asking for help; simply state what the problem is. In general, people will not quickly flock to your thread just because you claim that it is urgent."

Point 4: "If you have only written single paragraph" should be "If you have only written a single paragraph"

Point 3: Cross posting: Perhaps add something to the affect, "If you post in the wrong area, you can ask a moderator to move your thread to the proper forum."

In cross posting you also write " lack of comments is not a sign that you have posted in the wrong area". This might be a point on its own. I have seen a few issues where no comments appeared:

1 - The question was only asked 2 minutes ago... be patient (courteous), folks here all have lives, families, jobs, etc.
2 - Perhaps your question wasn't clear enough, provide more detail.
3 - Posted in the wrong area?

My final suggestion for now concerns followup. "If you ask a question, be sure to followup when someone takes the time to provide an answer or support to your problem. Even if you figure out the answer on your own, share your solution with others. You will gain respect by giving back to the community, and you show respect by thanking those that helped you and letting them know if the solution they provided was helpful or not."

Feel free to modify leave out or add any of these that you see fit to do something with.

Good work!

Groovounet
06-02-2011, 07:30 AM
Great job Alfonse!

I find the whole think quite wordy which is fine if it's easy to browse the text to find exactly what the reader is looking for. Programmers are lazy, they won't read the whole think.

I think the section "Posting Guidelines:" is really good on that regard with title and subtitle which is really missing for the first and last part.

It would be good to add a link under "glGetString" to the man pages but also for FreeGLUT and GLFW.

RefleX
06-07-2011, 03:33 AM
You can also add the following:

Respect other members and their advice. If you disagree with anything another member has posted please reply in a constructive and positive manner. This will reduce the amount of flame wars and keep a thread on topic.

ZbuffeR
06-07-2011, 09:42 AM
Great job indeed.
I also find it is quite verbose and could be trimmed down, because in its current form the kind of people that would need it most will never read it completely...

I really like the short phrase in bold at the beginning of each "Posting Guidelines" points, it should be done for the first section too, as well as "Posting Code".

V-man
06-10-2011, 07:41 AM
Why don't old threads get locked? Some forums lock old thread after 3 months. People should just make a new thread and include the link to the older thread if you want people to look at it.

Noobs just do a google search and just ask their question in whatever thread they find.


This will reduce the amount of flame wars and keep a thread on topic.
What flame wars?
I do recall some DX fans coming here and trying to start one but that's ancient history.

Khronos_webmaster
06-21-2011, 07:05 AM
Would you like to see threads locked after a certain amount of time, how much time? What about if a question has been answered, should the thread get locked?

ZbuffeR
06-21-2011, 07:35 AM
I think threads could automatically be locked after 1 year. It would prevent revival of very old threads whitout blocking useful continuation after several months (like seen on some threads related to driver bugfixes ... updates can be long).

For your second question, not sure how that could be useful. Quite a few times someone comes back after "it works" to post "not quite, because..."

Alfonse Reinheart
06-21-2011, 07:10 PM
Here's my near-final version. I've been going back and forth about whether the "Before you post" or the "Posting Guidelines" should come first. There is a good argument for either being first. Any suggestions?

The best way to get help in this forum is to ask your questions in a way that makes it easiest for us to give you help. Consider the following to be a series of informal guidelines for posting questions.


Before you post:

Before you ask questions of others, it is respectful to put forth some effort in solving the issue yourself. It is generally faster for you (if your question has already been answered) and it keeps down the number of redundant or simple questions the forums receive. To this end, you should do the following before asking a question:

1: There are many good sources of information on OpenGL available on the web. You should check these before posting.
There are reference pages available covering the OpenGL API. There are pages covering OpenGL versions 2.1 (http://www.opengl.org/sdk/docs/man/), 3.3 core (http://www.opengl.org/sdk/docs/man3/), and 4.1 core (http://www.opengl.org/sdk/docs/man4/), as well as GLSL (all versions) (http://www.opengl.org/sdk/docs/manglsl/). The OpenGL Wiki (http://www.opengl.org/wiki/Main_Page) is a good source of information. Pages of interest include the FAQ (http://www.opengl.org/wiki/FAQ), Common Problems (http://www.opengl.org/wiki/Common_Mistakes), and Getting Started (http://www.opengl.org/wiki/Getting_started) pages.
2: Google is your friend. Or Bing, if you prefer. Or whatever searching service you prefer; it doesn’t matter. It would be best for all involved if your question could not be answered via a simple search based on the terms you’re interested in.

3: Search the forum. The OpenGL forums have an extensive search function, and the forums have been around for years. It is very possible that your question has been asked and answered before. Make use of those search abilities before posting (but don’t post in the thread you find unless it is a recent thread).

4: This forum is an OpenGL forum, not a general coding forum. So try to focus your question(s) on OpenGL matters. Questions should be about the OpenGL API, issues around the API (WGL/GLX matters), shaders, or something directly related to those things. Questions generally about graphics matters related to OpenGL are fine. General graphics questions are also acceptable, though OpenGL should be involved at some point.

5: This is an OpenGL forum, not an OpenGL ES or WebGL forum. While ES is a similar specification to desktop OpenGL, it is not exactly the same. Forum users are more likely to be able to answer desktop OpenGL questions than ES questions. You can certainly ask questions about these things, but if you do, please state up-front that you are asking questions about ES or WebGL. Also, you are more likely to get ES (http://www.khronos.org/message_boards/viewforum.php?f=19&amp;sid=a252f897090dfe0828f5da581f0 f91f8) or WebGL (http://www.khronos.org/message_boards/viewforum.php?f=34&amp;sid=a252f897090dfe0828f5da581f0 f91f8) help by asking on the Khronos forums dedicated to those subjects.

6: Is your question about a homework assignment? If so, remember that the purpose of homework is to help you learn. It does you no good to be told the answer to a homework assignment. Also, this is cheating, which is generally frowned upon in academic institutions.


Posting Guidelines:

1: Use a clear thread title. A good thread title should be a very short summary of the problem. For example, if your problem seems to be with textures, then the word “texture” should be somewhere in the title. Titles probably should be 8 words or less, though more can be used when necessary.

There is also no need to use words like “please help” or “urgent” in your thread title. By posting in the forum, you are already asking for help; simply state what the problem is. And people will generally not quickly flock to your thread just because you claim that it is urgent.

2: Put your question in the correct forum area. There is a text description for what each forum area is for, so this should not be particularly difficult.

The platform-specific forums are not for users working on a particular platform. They are for issues related specifically to that platform. So you should not ask a question in the Windows forum just because you are developing a Windows application. Only ask there if you are having issues setting up an OpenGL window on Windows. If you are using FreeGLUT or a similar toolkit that abstracts platform dependent issues, then you probably should not be posting in a platform-specific forum.

The most vexing issue is probably the difference between the “Beginners” forum and the “Advanced” forum. The distinction is not simple, and generally you’ll get help in either one. A good rule of thumb is that if you don’t feel comfortable with OpenGL as a whole yet, then your question probably should go to “Beginners”.

3: Do not post the same thread in multiple forum areas. This is called "cross-posting," and is not necessary for you to get help. If you make a post in the wrong forum area, only post again in the right one if people have not already started to comment on your current one. Also, lack of comments is not a sign that you have posted in the wrong area, so there is no need to post in “Advanced” if you didn't get a response in “Beginners”.

4: Clearly state your problem in your text. Make sure to include all relevant details. If you have only written single paragraph, that’s probably not enough detail. A single sentence is completely out of the question. While overdoing the detail is possible, it’s better to put too much detail in than not enough detail.

Never just say “it doesn’t work;” that is almost never helpful, nor is writing a single sentence and posting a block of code. What you don’t want to do is engage in dueling dialog, where the first responder asks for clarification, you provide an additional detail, they ask for more clarification, and so on.

To this end, your post should include:
What the problem you’re having is. What the results you expect to see are. What you are actually seeing, and how it differs from what you expect to see.
Use pictures if it makes it easier to understand the issues around the problem. The more relevant information you provide (to a point), the more likely the forum users are to be able to solve your problem.

5: Supply all relevant information about your setup and system. This includes:
State your OS, graphics card, and driver version. At a minimum, include the results of glGetString for GL_VENDOR, GL_VERSION, and GL_RENDERER. State up front whether you are using shaders (if you don’t know, then you aren’t). If so, state what kind of shaders you are using (glslang, Cg, ARB assembly, etc), as well as version information about which version of shaders you are using. State if you are writing to core OpenGL 3.2 or above. State whether you are using a toolkit like GLUT, GLFW, etc. Also, stop using GLUT; use FreeGLUT instead. State if you are using a language other than C/C++. We can certainly work with other languages, but it's important to know up front what you are refering to.
6: Do not post in old threads. If your search on this site unearthed a thread with a similar question to yours, but that thread hasn’t been posted in for more than 6 months, resist the urge to post in that thread, no matter how appropriate it may seem. Simply make a new thread; it will decrease confusion for readers of the thread. If you need to refer back to the old one, post a link in your description.

7: Do not request private help. Specifically, do not ask a question openly in the forum, then provide your email address and tell people to mail you the answer.

The purpose of a discussion forum is to discuss things openly. This allows everyone to share in the discussion as well as allowing everyone to share in the results. By asking for private help, you are taking away from the forum without giving back. As you might imagine, this is quite impolite.

Something similar goes for private messages. Do not post a thread and then private message forum members as a way of advertising it.


Formatting your post:

Proper formatting is always a good idea. If someone can’t read your post, they can’t answer your question.

1: Avoid net-speak and use reasonable English. Common mistakes include:
Using “u” instead of “you”, or similar improper contractions. Not capitalizing the word “I” or the first letter of sentences. The use of multiple exclamation points or question marks at the end of a sentence. The use of ellipsis marks (...) instead of periods.
2: Paragraphs should have an empty line between them. Also, paragraphs should usually consist of more than one sentence. Putting each sentence on a paragraph is not necessary and makes the post difficult to read.

3: Word wrapping is automatic. You do not need to manually word wrap by pressing <enter> at the end of a line.

Posting source code:

It is perfectly fine to post source code. The important question is which code and how much to post. Knowing which code is relevant is not exactly easy when you don’t know how things work and what exactly is wrong. It’s a catch-22: if you post too much code, most people won’t bother sifting through it to find your problem. But if you don’t post enough code, then they’ll have to ask you to post more since the problem doesn’t appear to be in what you posted. You will have to use your own judgement to decide which source to post.

If you do post code, make sure to properly format it. Always use code tags. These tags look like this:
code goes here [/code ], except without the space between the ‘e’ and the ‘]’ of the tags. If the source code in question is long (more than a half-page or so), enclose the code tags in spoiler tags. This will create a small box that the user can press a button in to display the contents. Spoiler tags look like this: [spoiler ] stuff goes here.[/spoiler ]. Again, remove the spaces in the tags to make them work. Properly formatted code looks like this:

[CODE]
void some_func()
{
glDrawArrays(...);
}


Make sure that the source code is properly tab indented. You don’t need to use any particular indentation style, but you need to have some kind of indentation to make it easier to read. Just copy and paste it directly from your source files.

Users will generally assume your code is either C or C++. If it is not, then you should say so in the text preceding the source code.

If you are having trouble with shaders, post them as well. Make sure that the version of the shader language in question is clearly stated, either in the shader code with a #version statement or somewhere in your text.

ZbuffeR
09-02-2011, 07:37 AM
Any news about this being shown prominently to posters ?

Alfonse Reinheart
09-02-2011, 02:57 PM
Actually, I have a final version, if our webmaster would like to put it somewhere:

The best way to get help in this forum is to ask your questions in a way that makes it easiest for us to give you help. Consider the following to be a series of informal guidelines for posting questions.


Before you post:

Before you ask questions of others, it is respectful to put forth some effort in solving the issue yourself. It is generally faster for you (if your question has already been answered) and it keeps down the number of redundant or simple questions the forums receive. To this end, you should do the following before asking a question:

1: There are many good sources of information on OpenGL available on the web. You should check these before posting.
There are reference pages available covering the OpenGL API. There are pages covering OpenGL versions 2.1 (http://www.opengl.org/sdk/docs/man/), 3.3 core (http://www.opengl.org/sdk/docs/man3/), and 4.2 core (http://www.opengl.org/sdk/docs/man4/), as well as GLSL (all versions) (http://www.opengl.org/sdk/docs/manglsl/). The OpenGL Wiki (http://www.opengl.org/wiki/Main_Page) is a good source of information. Pages of interest include the FAQ (http://www.opengl.org/wiki/FAQ), Common Problems (http://www.opengl.org/wiki/Common_Mistakes), and Getting Started (http://www.opengl.org/wiki/Getting_started) pages.
2: Google is your friend. Or Bing, if you prefer. Or whatever searching service you prefer; it doesn’t matter. It would be best for all involved if your question could not be answered via a simple search based on the terms you’re interested in.

3: Search the forum. The OpenGL forums have an extensive search function, and the forums have been around for years. It is very possible that your question has been asked and answered before. Make use of those search abilities before posting (but don’t post in the thread you find unless it is a recent thread).

4: This forum is an OpenGL forum, not a general coding forum. So try to focus your question(s) on OpenGL matters. Questions should be about the OpenGL API, issues around the API (WGL/GLX matters), shaders, or something directly related to those things. Questions generally about graphics matters related to OpenGL are fine. General graphics questions are also acceptable, though OpenGL should be involved at some point.

5: This is an OpenGL forum, not an OpenGL ES or WebGL forum. While ES is a similar specification to desktop OpenGL, it is not exactly the same. Forum users are more likely to be able to answer desktop OpenGL questions than ES questions. You can certainly ask questions about these things, but if you do, please state up-front that you are asking questions about ES or WebGL. Also, you are more likely to get ES (http://www.khronos.org/message_boards/viewforum.php?f=19&amp;sid=a252f897090dfe0828f5da581f0 f91f8) or WebGL (http://www.khronos.org/message_boards/viewforum.php?f=34&amp;sid=a252f897090dfe0828f5da581f0 f91f8) help by asking on the Khronos forums dedicated to those subjects.

6: Is your question about a homework assignment? If so, remember that the purpose of homework is to help you learn. It does you no good to be told the answer to a homework assignment. Also, this is cheating, which is generally frowned upon in academic institutions.


Posting Guidelines:

1: Use a clear thread title. A good thread title should be a very short summary of the problem. For example, if your problem seems to be with textures, then the word “texture” should be somewhere in the title. Titles probably should be 8 words or less, though more can be used when necessary.

There is also no need to use words like “please help” or “urgent” in your thread title. By posting in the forum, you are already asking for help; simply state what the problem is. And people will generally not quickly flock to your thread just because you claim that it is urgent.

2: Put your question in the correct forum area. There is a text description for what each forum area is for, so this should not be particularly difficult.

The platform-specific forums are not for users working on a particular platform. They are for issues related specifically to that platform. So you should not ask a question in the Windows forum just because you are developing a Windows application. Only ask there if you are having issues setting up an OpenGL window on Windows. If you are using FreeGLUT or a similar toolkit that abstracts platform dependent issues, then you probably should not be posting in a platform-specific forum.

The most vexing issue is probably the difference between the “Beginners” forum and the “Advanced” forum. The distinction is not simple, and generally you’ll get help in either one. A good rule of thumb is that if you don’t feel comfortable with OpenGL as a whole yet, then your question probably should go to “Beginners”.

3: Do not post the same thread in multiple forum areas. This is called "cross-posting," and is not necessary for you to get help. If you make a post in the wrong forum area, only post again in the right one if people have not already started to comment on your current one. Also, lack of comments is not a sign that you have posted in the wrong area, so there is no need to post in “Advanced” if you didn't get a response in “Beginners”.

4: Clearly state your problem in your text. Make sure to include all relevant details. If you have only written single paragraph, that’s probably not enough detail. A single sentence is completely out of the question. While overdoing the detail is possible, it’s better to put too much detail in than not enough detail.

Never just say “it doesn’t work;” that is almost never helpful, nor is writing a single sentence and posting a block of code. What you don’t want to do is engage in dueling dialog, where the first responder asks for clarification, you provide an additional detail, they ask for more clarification, and so on.

To this end, your post should include:
What the problem you’re having is. What the results you expect to see are. What you are actually seeing, and how it differs from what you expect to see.
Use pictures if it makes it easier to understand the issues around the problem. The more relevant information you provide (to a point), the more likely the forum users are to be able to solve your problem.

5: Supply all relevant information about your setup and system. This includes:
State your OS, graphics card, and driver version. At a minimum, include the results of glGetString for GL_VENDOR, GL_VERSION, and GL_RENDERER. State up front whether you are using shaders (if you don’t know, then you aren’t). If so, state what kind of shaders you are using (glslang, Cg, ARB assembly, etc), as well as version information about which version of shaders you are using. State if you are writing to core OpenGL 3.2 or above. State whether you are using a toolkit like GLUT, GLFW, etc. Also, stop using GLUT; use FreeGLUT instead. State if you are using a language other than C/C++. We can certainly work with other languages, but it's important to know up front what you are refering to.
6: Do not post in old threads. If your search on this site unearthed a thread with a similar question to yours, but that thread hasn’t been posted in for more than 6 months, resist the urge to post in that thread, no matter how appropriate it may seem. Simply make a new thread; it will decrease confusion for readers of the thread. If you need to refer back to the old one, post a link in your description.

7: Do not request private help. Specifically, do not ask a question openly in the forum, then provide your email address and tell people to mail you the answer.

The purpose of a discussion forum is to discuss things openly. This allows everyone to share in the discussion as well as allowing everyone to share in the results. By asking for private help, you are taking away from the forum without giving back. As you might imagine, this is quite impolite.

Something similar goes for private messages. Do not post a thread and then private message forum members as a way of advertising it.

8: Do not simply post a link to your question on another website/forum/etc. Post the entirety of your question here. It is fine to post links to images or code, but the actual explanation of your issue should be in the post itself.


Formatting your post:

Proper formatting is always a good idea. If someone can’t read your post, they can’t answer your question.

1: Avoid net-speak and use reasonable English. Common mistakes include:
Using “u” instead of “you”, or similar improper contractions. Not capitalizing the word “I” or the first letter of sentences. The use of multiple exclamation points or question marks at the end of a sentence. The use of ellipsis marks (...) instead of periods.
2: Paragraphs should have an empty line between them. Also, paragraphs should usually consist of more than one sentence. Putting each sentence on a paragraph is not necessary and makes the post difficult to read.

3: Word wrapping is automatic. You do not need to manually word wrap by pressing <enter> at the end of a line.

Posting source code:

It is perfectly fine to post source code. The important question is which code and how much to post. Knowing which code is relevant is not exactly easy when you don’t know how things work and what exactly is wrong. It’s a catch-22: if you post too much code, most people won’t bother sifting through it to find your problem. But if you don’t post enough code, then they’ll have to ask you to post more since the problem doesn’t appear to be in what you posted. You will have to use your own judgement to decide which source to post.

If you do post code, make sure to properly format it. Always use code tags. These tags look like this:
code goes here [/code ], except without the space between the ‘e’ and the ‘]’ of the tags. If the source code in question is long (more than a half-page or so), enclose the code tags in spoiler tags. This will create a small box that the user can press a button in to display the contents. Spoiler tags look like this: [spoiler ] stuff goes here.[/spoiler ]. Again, remove the spaces in the tags to make them work. Properly formatted code looks like this:

[CODE]
void some_func()
{
glDrawArrays(...);
}


Make sure that the source code is properly tab indented. You don’t need to use any particular indentation style, but you need to have some kind of indentation to make it easier to read. Just copy and paste it directly from your source files. Also, when pasting, make sure that extra line spaces don't come out in the pasted code. Sometimes, you get effects like this:



void some_func()

{

glDrawArrays(...);

}



Use the preview button to check to see if the code came out correctly.

Users will generally assume your code is either C or C++. If it is not, then you should say so in the text preceding the source code.

If you are having trouble with shaders, post them as well. Make sure that the version of the shader language in question is clearly stated, either in the shader code with a #version statement or somewhere in your text.

MalcolmB
09-16-2011, 11:56 AM
What this is *badly* missing is guidelines for replying to questions as well. This is entirely one sided without dealing with the aggressive and condescending replies that can turn people away from this forum.

A few possible Guidelines:

* No questioning *why* someone wants to do something as a way to try to make the question pointless.

* Just because you don't know the answer, doesn't mean there isn't an answer. If you can't say 'My post will help make this thread more helpful', then don't post.

* If someone is trying to do something strange that you've never tried, don't post saying it won't work unless you are referencing the OpenGL spec directly. This is particularly true when talking about driver behavior.

* If you don't know the answer to the question, don't pollute the thread with other pedantic comments.

* Don't derail a legitimate question which is clearly understandable because the poster made a mistake on the OpenGL nomenclature.

Alfonse Reinheart
09-16-2011, 03:08 PM
No questioning *why* someone wants to do something as a way to try to make the question pointless.

Except that in many cases, knowing why someone wants to do something will lead you to show them a better way of getting what they want. Knowing why is almost always a vital clue to knowing whether the approach they're taking is correct.

MalcolmB
09-16-2011, 05:17 PM
Many people come here having done their research, decided 'ok, this is the extension I need to use to do this, now how do I use it?', and have a question related to the usage of that extension. 'Why' is not a valid question in those cases, but comes up all too often in those cases.

Alfonse Reinheart
09-16-2011, 05:44 PM
Many people come here having done their research, decided 'ok, this is the extension I need to use to do this, now how do I use it?', and have a question related to the usage of that extension.

And many other people don't. Many other people just download some code, poke at it a bit, something goes wrong, and then they ask for help. How do you tell one from the other? And do you honestly believe that the former outnumber the latter?

Unless the question actually explains that they did research and have determined that the alternatives are inappropriate for their needs, it would be wrong to assume that they have that knowledge. There's no harm in asking; the worst case is that they simply respond by saying that they can't use alternatives because of X, Y and Z.

It's also important to understand that this is a discussion forum, not a dedicated Q&amp;A site (http://stackoverflow.com/). While it can serve as the latter, people are going to have different opinions about things, and those opinions are going to be expressed. And even on dedicated Q&amp;A sites, people will often ask, "Why are you doing X when you could be doing Y?"

And more often than not, there is no justification for it.

ZbuffeR
09-17-2011, 12:06 AM
Indeed MaclcomB, your first point prevents to fix the XY problem (http://www.perlmonks.org/index.pl?node_id=542341).

I quite agree with your other points though.

MalcolmB
09-20-2011, 10:18 AM
I'm not saying don't ask why in all cases. I'm saying don't ask why simply because you don't know the answer, as a way to change the conversation away from the question you can't answer.

carsten neumann
10-28-2011, 03:38 PM
Can we have this at least stickied even if it's not elevated to official posting guide status?
I keep searching for it in order to link it (is there a better way?), which is a bit cumbersome.

Khronos_webmaster
11-03-2011, 07:09 AM
Unless I hear any valid objections within the next day or two, I'm going to copy the guidelines to Announcements area and make them a site announcement as well as link to them from the Board Rules, which must be accepted by new registrants.

Khronos_webmaster
11-13-2011, 08:52 AM
The guidelines are posted here (http://www.opengl.org/discussion_boards/ubbthreads.php?ubb=showflat&amp;Number=305969&amp;an=12#Po st305969), set to be a site wide announcement, and are linked to from the board rules for people to read when they register a new account.