Exist: Help people get help with eXist

[joewiz]

New users / contributors are understandably unsure how to get help. As one recent example stated when asked to post his questions to exist-open instead of as an issue:

Sorry, I'll use the mailing list. By the way this is not mentioned in the exist-db.org website, where is suggested to use the Github also for questions: "Community: If you'd like to contribute, ask questions or are looking for the sourcecode [sic] please see our github [sic] page for details."

We could help users who start to file an issue by creating a CONTRIBUTING.md file, as documented at https://help.github.com/articles/helping-people-contribute-to-your-project/. This page also documents how to create issue and pull request templates that encourage people to supply, for example, version numbers.

Perhaps we can draw from (and update, if needed) this underutilized page in the documentation: http://exist-db.org/exist/apps/doc/getting-help.xml.

A basic question users should readily be able to find:

1. If I have a question, where should I ask it?
2. If I think there's a bug but not certain, where should I ask it?
3. If I know there's a bug and have a reproducible test, where should I post it?

And for all of the above: what minimum set of information should I always include with requests?

[dizzzz]

I actually started a long time ago on this..... but the work got lost. My idea was

• to use CONTRIBUTING.md as the document describing how to contribute code to the codebase
• use README.md as a kind of small collection of links, e.g. to the CONTRIBUTING.md, your referred help page, links to misc resources
• add a ISSUE and PR template as described here to get better info into the PRs and Issues...

[joewiz]

@dizzzz Cool, those sound like great ideas.

I realized that there's no link to the HipChat room. I always have to search the mailing list to find Wolfgang's original email with the invitation link. Assume we aren't actively dissuading people from using it, we could add this link where appropriate: https://www.hipchat.com/gEBQ3SNfp. The only problem with that link is that people show up as guests, but it would be document the method for creating a proper HipChat account and joining the eXist-db room as a non-guest.

Another source of confusion is Stack Overflow versus exist-open. Perhaps it would be useful to have a statement somewhere about Stack Overflow: "Some members of the eXist community monitor the exist-db tag, and it's a good service and we do not discourage posting there, but at present most members of the eXist community are on exist-open. So for broadest impact, write to exist-open. Cross posting to exist-open and stack overflow is discouraged, as it leads to duplicate efforts."

[windauer]

@joewiz, @dizzzz thanks for pushing this forward! Regarding Hipchat: meanwhile there is an URL that allows users to create a HipChat account for the eXistdb Hipchat room. Only thing is, that HipChat itself is warning to make this public, probably because of robots. But I think we should wait, till this really happens so here is the link: https://existdb.hipchat.com/invite/300223/6ea0341b23fa1cf8390a23592b4b2c39 (if we experience issues, we can always create a new link, which invalidates the old one, we only have to make sure than, we don't have the old one online any more).

[joewiz]

@windauer Thanks, I included the HipChat invite link in #1261.

Do we agree that @dizzzz's #1255 closes this issue?

[duncdrum]

Actually should the Web page also mention gitlab now in addition to github?

[adamretter]

@duncdrum No. There should not be any public projects on GitLab. All public projects should be on the GitHub.

[joewiz]

@adamretter Hmm. See the public apps on gitlab.exist-db.org. The TEI Publisher apps are there. I imagine there are aome advantages to developing those apps there.

[joewiz]

@duncdrum Could you expand on what you were proposing about GitLab?

[adamretter]

@joewiz I did discuss with @wolfgangmm and he agreed these things should be in the Github and he would move them.

[joewiz]

Ah, great, good to hear! Much greater visibility + better security (HSTS, 2FA) on GitHub.com seemed like compelling advantages to me.

[duncdrum]

@adamretter, I agree that would be better. Basically any app from the exist team that isn't marked as beta, runs on stable, and is in the public repo should be on github imv.

@joewiz, I m thinking of the out-of-the-box experience for new users (given my background in using exist with university students). User runs exist for the first time, and sees an app that he/she is interested in, installs via Dashboard. To the user there is no difference between eXide, monex, and teiPublisher, or packagemanger(2.0). Yet to report issues or make feature suggestions, we now have to go to two separate places github and gitlab. What's worse gitlab isn't explicitly mentioned anywhere.

[adamretter]

Indeed. My argument was not to add yet another channel.

[duncdrum]

TEI-publisher is the last one standing, and on its way to being migrated A-171127-1

[joewiz]

We agreed to kill all references to GitFlow - I just spotted a couple still lingering! https://github.com/eXist-db/exist/search?q=gitflow