How should I ask a question in the Forum if I want to receive useful answers?

Ralph Schoon (63.5k●3●36●46) | asked Aug 04 '15, 3:21 a.m.
FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER
edited Aug 04 '15, 5:41 a.m.

I am looking at the forums and I notice that the quality of a lot of questions lately is insufficient to really allow to help. Therefore a lot of energy is spent in getting the information that should be available in the first place.

This gets quite frustrating to be honest, assuming that this forum is used by professionals, mostly.

So, how should I ask a question in the forum if I hope to get an answer?

Comments

Ralph Schoon commented Aug 04 '15, 4:24 a.m. | edited Jun 28 '16, 6:22 a.m.

FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

PS: The intent of the answer to this question is to serve as a best practice information that can be used in questions that don't provide enough information.

Accepted answer

permanent link

Ralph Schoon (63.5k●3●36●46) | answered Aug 04 '15, 3:43 a.m.
FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER
edited May 30 '17, 2:15 a.m.

You should have run a search engine search already, before you even consider to ask. To limit the search scope to this site add site:jazz.net behind the keywords.

Read the first 10 results. You'd be surprised how many questions answer themselves that way, plus you learn a lot by doing it. Refining: If doing so, just finding a bunch of similar questions, maybe several years old, not reading the information and post a new answer like "How did you solve this" to several of such questions is not really professional. It is not a good idea to do so. Rather read the information provided with the questions and create a new question if needed.

Questions, where the same two lines of text is pasted in to the subject and the question body drives away professional users on the forum, because it shows no effort and thought was spent in creating the question.

Questions with statements in the subject and no question in the body also drives away professional users in the forum for the same reason.

To create a good question follow these steps:

In the Subject, create a good subject that touches on the problem and really is a question.
In the question body,

Clearly describe what you do or want to do, and what the problem/question is
Explain why you want to do this and what you want to achieve with it - often problems are not problems in the tool, but knowing how to achieve certain goals; knowing what the intent is often directs to completely different answers
Provide the tool name and the version of the tool you use
If there are errors, provide the error message - before you ask the question, carefully read the error message, think about it and what it means and ideally check the application log files before asking a question
If this is around setup, upgrade and the like, provide the information about the topology you use, the operating systems, their versions, the databases, their versions, the application servers and their versions; anything that might be special in your environment could be of interest
If you use a UI, provide the information about which UI you use; browser, other client
Use screen shots where possible. Please note, that you need 50 reputation on the forum to post images, if you don't yet have that reputation, you can upload the screen shots to some other site e.g. dropbox and put the link into the question.

Tag the question with the product name you are using. Choose one or two reasonable tags. If a tag is unfamiliar to you, don't choose it. E.g. Jazz-Foundation is a very popular tag that is used often but probably fits 2% of the cases where it is used. If there is no matching product name of the form rational-....... for your problem, consider to find another forum that deals with the product and question you have.

If you have questions about the API use extending (for Java API) or OSLC or REST for web based API as tag.
If you ask about JavaScript or how to modify work items use attribute-customization as tag.
If you have questions around agile methodologies use agile as tag. Don't use it just because you have the agile template deployed or because it is hip today.

API Code:
Don't just paste your code in a question and hope someone will remote debug your code. All the users here are professionals and have a day job that does not leave them the freedom to do this.

If you want to discuss code and have an error that shows with the code, carefully consider the error. Provide the error message and the line it occurs in addition to the code in the question. Looking into the log files before doing this, applies again. Make sure to point at the line that thows an error in your code, as only you can do that.
If you want to discuss code, you should be able to debug it. If you are not, get your debug environment up and running for the server and the client API. Run the snippets that come with the Plain Java Client Libraries and understand the basic structure for RTC automation using the Java API. Consider following this post about getting started using the API.
If you want to extend the server run the whole Rational Team Concert Extensions Workshop before you try anything yourself.

JavaScript:
Before you ask about Java Script related questions read the wiki information provided, especially the API for JavaScript section and carefully read the Process Enactment workshop lab 5. Ideally run the workshop.
Make yourself aware that the JavaScript API is limited and you can not get at all the information you might like. Learn how to debug Java Script where you can debug it.

If you follow these best practices the forum experience will greatly improve.

Thank you!

The Jazz Team.

Note on Extending:
Please be aware that extending the tools should not be taken lightly. It is expensive, takes skills, needs to be maintained, can have impact on performance and, in general user experience. Never do it because it can be done. There has to be a real business case in order to consider extending the tools. The fewer you extend, the better.

Geoffrey Clemm selected this answer as the correct answer

Comments

sam detweiler commented Aug 04 '15, 12:51 p.m.

all of that is well and good.. If you even know where you are..

In many cases I don't KNOW what I am asking about.. so you get the best formulation of the idea as it appears in my head.. but from your perspective the words may be completely unintelligible. I notice that for a lot of our new users, english is not their primary language.

I've been doing forums of one sort or another for over 40 years. (internal in IBM originally, and externally). and the net ism people don't know what they are 'supposed' to do, and never will. I just take it as part of the discovery process of helping them.

I never search.. cause search is terrible. I have NO idea what terms to use. my example of this is that there MUST be a good restaurant I would like to go to in New York City, while I live near Austin Texas. I have no idea what names to search under.. or food type, or location, or ... so I stare at the search box, then go ask someone.

I tried to search yesterday for an RTC workitem I KNOW exists, but after 10 minutes, and 1000's of uselessly returned workitems, I gave up.

Ralph Schoon commented Aug 04 '15, 1:14 p.m. | edited Aug 04 '15, 1:17 p.m.

FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

Sam, your questions are generally good. If you are lost, explain what you want to do/achive and why and the usual details around your environment. That is usually manageable and way more than some of the questions provide. I am sure you have seen them.

I generally do search using a search engine and limit to this site. Many of my answers contain these links. I try 1 or two search term patterns. But I agree, sometimes I can't find questions I answered yesterday.

If we don't guide the users, they won't learn. This is mainly also a vehicle to point users int the correct direction. And I don't have to write it over and over.

I agree with the language barrier, but as you know English is also not my primary language and one can learn.

I agree with the terms, so the what and why, even using the wrong terms is a big help.

sam detweiler commented Aug 04 '15, 1:19 p.m.

from long frustrations like you mention, I have learned to go back and cleanup my title and initial question, once i learn more about ho to help focus the resources of those who helped me. all for later user consumption, should they be so 'lucky' to find one of my topics. but that takes time and energy that most users don't have, or don't have experience at doing. (or the forum tools stink at supporting)

I hear your cry for help, but I have never found a solution that makes a difference

Ralph Schoon commented Aug 04 '15, 3:29 p.m. | edited Aug 04 '15, 3:29 p.m.

FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

You are probably right. Luckily it is my decision where and if I spend my time. Thanks for your contribution Sam, as always it is greatly appreciated.

Geoffrey Clemm commented Aug 04 '15, 5:36 p.m. | edited Aug 04 '15, 5:37 p.m.

FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

I believe that the simple guidance that Ralph provides above is adoptable by anyone, native language speaker or not. Note that he isn't requesting perfect English ... he is just asking that you title your question in the form of a meaningful question. Specifying what version and what tool you are using does not require deep tool expertise or language skills. Suggesting you at least look at the top 10 hits from google search on your question not only can save the poster a lot of time, but also goes far to ensures that they are asking an actual question (googling "problem with the API" will of course get you nothing useful ... because you didn't ask a sensible question). I also applaud anyone who goes back and edits their question (and/or their comments and answers).

ed Neubecker commented May 29 '17, 10:15 p.m.

JAZZ DEVELOPER

Here is tip I follow myself: I tend to also add screen shots with annotations to help understand the context of questions I post here. Screen shots take more of my time to collect and annotate, but since they help me gain useful answer to my question I view it as time well spent ;)

Ralph Schoon commented May 30 '17, 2:21 a.m. | edited Jun 01 '17, 3:21 a.m.

FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

I would not spend all my time enabling users with the API if I would think it is an absolute no go. But I have seen too many customers going crazy on extending tools, putting man years into it and running into

Rendering the tool useless because the process got overly complex
Performance issues due to excessively extending the tools
Getting stuck, unable to upgrade because the customization prevents that either by dependencies or need to change APIs or need for testing
Inability to maintain the extensions because the developers left the company

Ralph Schoon commented May 30 '17, 2:27 a.m. | edited Jun 01 '17, 3:22 a.m.

FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

So what I am constantly saying is to make sure what you do has business value and needs to be done. If so, go ahead. Use common sense and always question if this is really needed. I have seen issues over and over in the forum. A typical pattern:

Management wants mandatory attributes and gets them, no questions asked, no reason documented
More mandatory attributes get added over time, rarely ever they get removed
Users complain about having to fill in 50 mandatory attributes
Someone tries to write an automation to fill in the mandatory attributes

Ralph Schoon commented May 30 '17, 2:28 a.m. | edited May 30 '17, 2:32 a.m.

FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

Just don't extend the tools, because you are "under the impression that all of the wonderful opportunities made available by Java was one of the drivers behind moving away from Classic DOORS to NG" and you want to explore said opportunities.

Have a clear understanding of the business value, the budget, the resources and then do it right, including documentation someone can follow up if you leave the company.

Ralph Schoon commented May 30 '17, 2:30 a.m.

FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

Thanks Ed, I incorporated that into the answer, good point. I also added information that new users can not include images due to lack of reputation and how to use links to other web sites.

Ralph Schoon commented Jun 01 '17, 3:24 a.m.

FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

See my comments above. My comment there is based on experience.

Have a clear understanding of the business value, the budget, the resources and then do it right, including documentation someone can follow up if you leave the company.

showing 5 of 11 show 6 more comments

One other answer

Most liked answers ↑|Newest answers|Oldest answers

permanent link

Steve Dennehy (41●2●5) | answered May 29 '17, 9:59 p.m.
edited May 29 '17, 9:59 p.m.

"Note on Extending:
Please be aware that extending the tools should not be taken lightly. It is expensive, takes skills, needs to be maintained, can have impact on performance and, in general user experience. Never do it because it can be done. There has to be a real business case in order to consider extending the tools. The fewer you extend, the better."

I was under the impression that all of the wonderful opportunities made available by Java was one of the drivers behind moving away from Classic DOORS to NG.

DXL was a pain, but it was powerful, and we used it to do pretty cool things. Now the developers are specifically advising against any customisation of NG.

Assuming that one solution will meet all use cases is just so sad.

Your answer

Register or log in to post your answer.

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

It's all about the answers!

Related questions

How should I ask a question in the Forum if I want to receive useful answers?

Accepted answer

One other answer

Your answer