search

textX / textX

Domain-Specific Languages and parsers in Python made easy http://textx.github.io/textX/
MIT License
778 stars 76 forks source link

How to handle, conserve and aggregate questions about TextX ? #139

Open Aluriak opened 5 years ago

Aluriak commented 5 years ago

I move here the conversation from #121.

Currently, there is three places to find questions & answers for TextX:

The questions are:

I've seen some projects relying officially and solely on SO for questions. That's good outsourcing : that website is well-known, well-referenced by search engines, and well-designed for the task. Most programmers have an account on SO nowadays, and all of them used it at least once.

Getting questions in three different places seems to me quite useless, and:

A big interest of SO is also that you can ask questions that are related to TextX, along with other packages, systems, details. IMHO, the official TextX question place should stick with pure TextX questions. In other words, leave the weird installation problems, the complex interleaving of techs and the ill-posed questions to the patience and knowledge of SO.

simkimsia commented 5 years ago

I think right now as it is fine. But we can start to slowly seed the questions in SO

SO also has stringent guidelines on what’s an objective question to ask.

Right now given that the load on questions is not that heavy we can live with GitHub as first point of query.

Every 6 months or so we cull the most frequently asked and update the FAQ

igordejanovic commented 5 years ago

@Aluriak, @simkimsia I fully agree, and I think it is the right time to set up the policy for asking question as the project will move under textX organization.

At the moment there isn't a big volume of questions involved so changing the venue where questions are asked won't make much damage. I do like SO as I think it brings several benefits, in addition you have pointed out, SO also maintains and builds user reputation which is motivating for contributors and advanced users to participate in answering questions. Hopefully, this will make more room for maintainers to do other stuff.

I would like to come up with a policy, announce it, put it in the visible places in the README and the docs and stick to it. When a user ask question in the wrong venue, instead of answering and adding to the confusion (as I did before) we should direct him/her to the correct place.

We could also maintain FAQ and update it from time to time as @simkimsia suggested. But, I guess after enough time, when the community grows a pool of Q&A at SO we might not need FAQ at all.

My vote goes to SO. The GitHub issues would be for issues/bugs/feature requests only.

goto40 commented 5 years ago

This all sounds good to me.

Did I understand correctly, that we will also maintain the FAQ? I find it important to keep all Infos together at some central location...

We could possibly merge the how-to file into the FAQ file...

Aluriak commented 5 years ago

Sounds like a unanimous vote for:

Note that questions of the FAQ may totally be moved to SO, Q&A style as they said.

I however agree with @goto40, keeping FAQ in the documentation is a wise choice (at least because it makes offline documentation complete).

For maintenance, a label new question could be assigned to questions that are not yet integrated in the FAQ, allowing the maintainers to easily spot the questions to add to FAQ every N months.

simkimsia commented 5 years ago

Just to summarize

I also prefer to always have a FAQ in documentation. Even if for offline access like what @Aluriak says.

By the way, I am completely new to textx and DSL in general. I will be a good guinea pig for really stupid beginner questions being asked.

Almost every other technical term used in the README is new to me. I will start asking questions here and after they are answered, I will transfer them to FAQ or SO. I think this is an interesting repo so it be good to get more attention to this repo this way.

simkimsia commented 5 years ago

By the way, I discover @goto40 self-dsl repo. And I think it contains some really useful stuff taht I find as a beginner. It has more stuff on XText than TextX but TextX is pretty good too.

I found the motivation and intro topics to be useful especially for beginners like me.

Not sure how @goto40 feels about incorporating some of the self-dsl info on TextX here.

At the least, I think it's beneficial to have links to the self-dsl repo from within the documentation here.

goto40 commented 5 years ago

All topics not covered for textX are part of the TextX unittest and textx docs. (at least I hope I forgot nothing). Most important is the technology indépendent basics.md part.

Also you have a sketch of a DSL python app project I use myself.

goto40 commented 5 years ago

@simkimsia, thank you for the feedback. If you find details missing for textX (given for xtext on self-dsl), give me a hint. I will be happy to clarify or add infos...

simkimsia commented 5 years ago

@goto40

Would be great if u can link the basics.md in ur comment to ur self-dsl else people might be confused. I agree that fundamental part is important.

Where’s the sketch u mention? I cannot find it

I still reading to understand.

goto40 commented 5 years ago

Within self dsl:

Basics: https://goto40.github.io/self-dsl/basics/

Textx project sketch: https://goto40.github.io/self-dsl/textx_project_setup/

igordejanovic commented 5 years ago

@simkimsia self-dsl should definitely be linked from textX docs. I just did that. Thanks for bringing this up. :)

So, we will go with SO as the place to ask questions. I would restrain from answering new questions here. When we start with the new policy, it will be announced on issue tracker and from that point on for any new question we should provide the link if the question is already answered or kindly ask the user to ask on SO and we should immediately close the question. In this way we'll avoid confusion and make everybody aware where question should be asked.

I agree that keeping FAQ in the docs with questions that are usually asked by newcomers is a good thing. As @simkimsia pointed out SO voting system will help for that. We could periodically select most voted questions and put them in FAQ.

For the already existing questions in the issue tracker that were not put in the FAQ we could transfer them to SO and then close them. @Aluriak yup, reading the post you provided it seems that it's perfectly fine to do that. After migration we'll remove question label from issues.

I think the same policy should be used for all projects that will be part of the textX organization (including Arpeggio).

igordejanovic commented 5 years ago

@goto40 Regarding how-to/FAQ, correct me if I'm wrong but I think their purpose is different. While FAQ should be some questions one could ask while learning the tool that could be a common gotchas and misunderstandings, how-to section is more an example-based approach on how to implement common tasks in developing a language.

goto40 commented 5 years ago

You are right. There may be an overlap if soemone ask a question 'how to do this and that'...

It is OK to keep it separated.

igordejanovic commented 5 years ago

I've put instruction on SO usage in README and docs. We can start with the migration. From now on, questions should be asked on SO.

We can start gradually moving questions from issue tracker to SO and/or FAQ page as the time permits. When the question is migrated please close it in issue tracker.

simkimsia commented 5 years ago

@igordejanovic Cool! I'll try to follow the usage instructions for my own selfish ends.

Basically I want to try to see if I can use TextX to build a DSL for Django model code generation. Every question I come up with and eventually solve (either on my own or with the community help) I will seed them in SO.