Update the help

[stscicrawford]

@tddesjardins mentions that we should consider moving emails from help[@]stsci.edu to point to the web portal where possible and appropriate. This is a catch all for the different supported HST software packages.

[pllim]

Note: For HST, it is https://hsthelp.stsci.edu . For JWST, it is https://jwsthelp.stsci.edu

[mcara]

This is a really bad way of notifying people: now every repository has an issue linked to this issue. I do not see any connection between many of the repositories listed here. This could have been communicated through e-mails, branch meetings, etc. GitHub should not be used as Slack, IMO.

[pllim]

@mcara , it was an experiment on my part. I apologize. Please PM your ideas to Tyler, as he requested on Slack. 😅

[mcara]

In addition, @pllim @stscicrawford @jhunkeler how should I implement @tddesjardins suggestion for the drizzlepac. Currently drizzlepac uses author_email field which is set to help@stsci.edu. Obviously this cannot be used for links to web portals.

Looking at https://docs.python.org/3.6/distutils/setupscript.html#additional-meta-data where would you recommend mentioning https://hsthelp.stsci.edu? I see only two reasonable fields: download_url and url.

Second question is: what do we provide in url and download_url??? Options:

1. http://drizzlepac.stsci.edu
2. https://github.com/spacetelescope/drizzlepac
3. https://drizzlepac.readthedocs.io/en/latest/
4. https://hsthelp.stsci.edu
5. https://astroconda.readthedocs.io/en/latest/

Which leads me to ask the following question @tddesjardins : who is even looking at author_email in setup.py and why is help@stsci.edu even an issue. I went to that portal and the second biggest thing that I see is e-mail option which sends e-mail to help@stsci.edu. Maybe we should do something different such as adding a page "how to contact" or "helpful links and contact..." whatever and have a more detailed description of how people can get more information, help, etc.?

[pllim]

@larrybradley and I briefly discussed author_email; I think we can just remove that field? (I mean, it isn't mandatory, right?)

Not sure about url etc. Like you said, who is even looking, right? Which brings up a good point, at least for DATB/SCSB branches, there should be a semi-consistent policy for "where to get help"... ServiceNow KB? JDox? HDox? Jaya (however you spell that Zope replacement)? @SaOgaz might have some ideas here.

[mcara]

And if we can come up with a common "contact us" page (like CODE OF CONDUCT.md that @pllim added to every repo), then we could ask @pllim (because of her possessing unmatched GitHub scripting skills) to insert said page to every repo. I could later customize it to add additional info, sites, etc.

[mcara]

author_email=helpdesk@stsci.edu seems so harmless: I can't imagine users digging through package source code, setup.py to find how to contact STScI. It just cannot be causing problems to helpdesk.

[pllim]

common "contact us" page

That is trickier, especially if you want to insert it into existing (or non-existing) Sphinx doc of the repo. However, a simple addendum to repo README is very doable indeed (just have to find a way to outsmart GitHub's "403 You have triggered an abuse detection mechanism..." error).

[pllim]

seems so harmless

You know what else seems harmless? Changing a single line in PyFITS. 😉

You never know who is going to look where. Better be safe than getting angry user asking why we are ignoring their requests sent to a defunct email address?

[mcara]

@pllim Did you actually try to go to https://hsthelp.stsci.edu/ and click on "Send e-mail" link on that web portal? It actually is help@stsci.edu(!!!) It is not "defunct" at all - it is still kicking!

[mcara]

I think that adding a "contact us" section to README is a very good idea instead of messing with setup.py which was not designed to deal with helpdesk issues. I would argue that it actually seems appropriate to send users to help@stsci.edu if they want to contact authors: helpdesk can triage messages appropriately.

[pllim]

Right, for now. But the plan is to retire that option. This is the first step.

[tddesjardins]

@mcara I do see your point about the author_email field, but what we're trying to do is less publicly advertise that the email is an option in an effort to get people to at least go to the web portal. I think it's fine to continue using author_email=help[at]stsci.edu for now (though that could change if we come up with a better solution), but README.md files and readthedocs pages etc. should instruct users to go to the web portal for assistance.

You are correct that the HST web portal does still present the email address as an alternative to using a MyST account (MAST and OPO do too). I think the language on the portal could be stronger to say that it is preferred to use the MyST account option. The JWST help desk does not actually have an email as a decision was made specifically against it. Advertising the web portals in all software then brings both missions in-line with each other for how users get assistance.

Finally, "help" is so generic sounding that it gets a lot of misdirected stuff that should have gone to MAST, JWST, or even more often than not ITSD. It's also been plastered all over STScI's webpages for several decades so that many bots have scraped it and send spam to it on a daily basis, requiring us to sift through tickets to find what's real and what's not. It was even put on the AAS mailing list at some point. That's one of several reasons why I want to move away from it (I have similar arguments about the phone number which gets almost daily fax noise voicemails). I don't think it's a perfect system, but the web portal allows people to use the knowledge base, self-triage for faster service, and monitor the status of all of their open tickets in one place. This is all part of our effort to get the word out.

I mentioned it in the slack git channel, but I do think that even if some people got spammed (for which I still apologize!) that this was a very effective way of informing everyone that this should be done. I even have several emails telling me I should update my repos, so I'm not immune. I do wonder if there could be a better way to do this in the future, for which I would appreciate feedback from people. I don't think an email and relying on meetings to get the word out would have been quite as effective, but maybe there's a different way to do it in future.

[stscicrawford]

@mcara Thanks for the discussion and you raise a few good points. I think it would be good to discuss some of the points and add recommendations about what should be in the setup.py or .cfg file.

Please see the original wording of my issue 'Where possible and appropriate' -- I do think author_email would be a place that would not be appropriate to update it at this time. We should however discuss what that value is or should be and while it isn't required, there should always be an email there in case of contact. While the help desk email is still available, it makes sense to keep using it for the time being, but we may want to determine what would be the best email to have in that variable especially if the help email becomes no longer available.

If the help email address is used elsewhere like the documentation, then when it is convenient, you should consider updating the documentation to point to the web portal.

[jamienoss]

My 2 cents (but I'm not entirely sure I understand what's wanted) - I think we are trying to inject information into the wrong layer, i.e. the src code itself. I believe the canonical place for such info is on/via GitHub itself, e.g. the repo wiki pages or the website description at the top of every-repo (or if that already points somewhere, very noticeably on that sites main/linked page). I think repo wiki pages to be the correct solution.

[SaOgaz]

In reference to @pllim's quesiton:

Which brings up a good point, at least for DATB/SCSB branches, there should be a semi-consistent policy for "where to get help"... ServiceNow KB? JDox? HDox? Jaya (however you spell that Zope replacement)? @SaOgaz might have some ideas here.

I don't have immediate answers for this except to say that it should NOT be Jihia (the zope replacement) unless we hear directly from DSMO etc that we're supposed to be using it for that. For now it seems sensible to focus our efforts on making sure our github/sphinx(rtd) docs are well rounded, and point people to the help website or to post issues on the repositories when they have questions.

[mcara]

@stscicrawford wrote:

... I do think author_email would be a place that would not be appropriate to update it at this time. We should however discuss what that value is or should be and while it isn't required, there should always be an email there in case of contact.

One option may be project_urls

[pllim]

Turns out the email is still widely used and ITSD has no plans to retire it.