PR: Add Troubleshooting links and blurb to various appropriate places in Spyder and doc #6137
Conversation
|
Hello @CAM-Gerlach! Thanks for updating the PR.
Comment last updated on January 16, 2018 at 09:14 Hours UTC |
.github/ISSUE_TEMPLATE.md
Outdated
| @@ -1,3 +1,9 @@ | |||
| **PLEASE READ:** Before posting this report, *please* carefully read our **Troubleshooting Guide** at https://github.com/spyder-ide/spyder/wiki/Troubleshooting-Guide-and-FAQ and search the issues page here for your error message and problem description, as the great majority of bugs are either duplicates, or can be fixed on the user side with a few easy steps. | |||
There was a problem hiding this comment.
Please break this at 80 characters or so, to not have it in a single line.
There was a problem hiding this comment.
I originally had it that way, but when it I tested how it would actually display on Github, it took up a a lot of excessive vertical space, since Github normally soft-wraps at 105 - 115 characters (at least in my browser) but respects the breaks in the file instead of rewrapping it properly and thus takes up ~50% more vertical room.
I don't like leaving really long lines like this either, but pragmatically, as the intended use is for display on Github, and this file will normally never be seen/directly used (it only has one change in its entire history since the day it was first committed a few years ago, compared to several dozen issues created each day—around a ~5,000:1 difference), it seemed to make more sense to optimize for where it will actually matter 99.96% of the time.
On the other hand, the narrower columns break nicely (except for the link, which I don't embed since its primarily for use in the raw/text view anyway) and help readability, It's not a big deal but just let me know which you prefer; you can compare them in the following screenshots illustrating the difference:
Editing View:
vs.
Rendered View:
vs.
.github/ISSUE_TEMPLATE.md
Outdated
| @@ -1,3 +1,9 @@ | |||
| **PLEASE READ:** Before posting this report, *please* carefully read our **Troubleshooting Guide** at https://github.com/spyder-ide/spyder/wiki/Troubleshooting-Guide-and-FAQ and search the issues page here for your error message and problem description, as the great majority of bugs are either duplicates, or can be fixed on the user side with a few easy steps. | |||
|
|
|||
| Also, if you do post an issue here, please describe step by step what you were doing when the error occured, in as much detail as possible. Otherwise, we will have to close your issue after one week (7 days) if we can't reproduce it. Thanks. | |||
There was a problem hiding this comment.
Also break this single line into multiple ones.
TROUBLESHOOTING.md
Outdated
| @@ -0,0 +1,492 @@ | |||
| Spyder Troubleshooting Guide | |||
There was a problem hiding this comment.
Is this file referenced from somewhere else? If not, my vote is to remove it and only leave the one in the wiki.
The problem with having two places with the same content is that (inevitably) they will diverge at some point in time.
There was a problem hiding this comment.
Is this file referenced from somewhere else? If not, my vote is to remove it and only leave the one in the wiki.
Fair enough; I figured this could be an objection, which is why I made it the last commit and not reference it elsewhere to make it easy to revert/remove if needed :)
The problem with having two places with the same content is that (inevitably) they will diverge at some point in time.
I wasn't going to include it for the same reason, but I ended up reconsidering it in the end after I specifically tailored it to only include the essentially static general troubleshooting content, which shouldn't change substantially at least over a reasonable timescale so it won't ever be that out of date, and it also includes a disclaimer and link at the top to the full/live version of the guide. Conveniently, the sections I included conveniently form the first and last chunk of the full version, and it uses the exact same Github markdown syntax, so all that needs to be done to update it every few months, if need be, is a simple copy and paste (which I am more than happy to do before each release, assuming there are actually any changes to the relevant sections).
On the other hand, the benefits of having it there aren't enormous, but the main reason is that troubleshooting help is included with the program itself, same as the other documentation, readme, contributing, etc (which in some cases could also be argued to be duplicative, and much harder to maintain due to different syntax and structure), and so if the user doesn't have access to the Internet (or Github, in some countries), they are still able to get help. As a secondary benefit, it also makes it (and the linked guide) more visible/easily accessible to those browsing the source locally or on Github, and serves as a tracked, publicly accessible backup of the key sections in case Github wikis ever go down or go away.
However, I'm certainly far from wed to it, and already mentally prepared myself for the possible breakup :). With the above in mind, let me know what you'd like me to do with it. Thanks!
|
@CAM-Gerlach, please post screenshots to see how this looks in all Spyder places you added this. Thanks! |
|
Sorry for the delay; just helped a friend get started using Spyder. I should have included them from the beginning, since already had to bring each one up anyway when checking that they displayed correctly. Here are the screenshots: About Spyder dialog: "Crashed last time" dialog: Error dialog: Help Menu item: Autogenerated error report Thanks! |
|
@CAM-Gerlach, this all looks very well! But since this PR involves adding new strings to the interface, I think I'll have to leave it for 3.2.7, sorry. You could also help us to finish PR #5346, which would go well with your work here. |
|
I know you worked very hard to get this done in very short time, but the strings this PR changes are quite visible, so I'd prefer not to push them in a rush and leave them for 3.2.7 instead. If you like, we could have that release by the end of the month with these changes, your PR about our README and the improvements to the report issues dialog I mentioned above. That would be a very good release too! What do you say? |
Okay...I assume for localization/internationalization? To be completely honest, I'm not quite sure how else one would expect to add a link and blurb to the UI...hieroglyphics? :P |
Oh, nice! I was actually planning to add something like that anyway, but it didn't seem time-realistic nor really in scope for this PR. |
Yep, that's right.
If a string changes, then it falls back to English automatically. So our international users would see (for example) our Issues dialog in English. And that's not really useful :-) |
Right, I understand that part, and we certainly don't want to leave Spyder's (many) international users out in the cold, especially on something important like this. Of course, the other issue is that the guide itself isn't translated... What I was referring to was why it wasn't clear that this would be the case at some point before now. :-) |
Sure. To be honest, while I was a bit miffed at first after pulling an all nighter (well, technically two) and calling in sick to work to make sure this got done, that was all my own (questionable) decisions, not anyone else's. If there's one lesson I've learned in life as I've grown and matured, there is everything to be gained from accepting life as it comes and focusing on making the best of it. Though, in all fairness it would have been nice to know a little beforehand :-) One such possibility: Since the github issue template (both the manual and auto versions) is not localized, and that would by itself be able to (one would hope) be seen by at least all the users submitting issues, would you accept for 3.2.6 another PR with just that change? EDIT 2: And what about the readme/docs, etc? Are those translated? I could either include them as well, or just move them over to #6084 since while I tried to avoid it, that would make sure there were no merge conflicts either way. This PR would then just be the actual UI changes (Menu Item/About/Crash/Error), keeping it more focused. But not sure how easy it is to just move around commits like that with Git... EDIT: Also, now that we have a little more time, would it be of any value to add a simple test for the help menu item, i.e. that it sends the proper request when clicked? Also, we could also use requests or something to test that the trouble_url doesn't 404... |
|
I can do the French translation whenever you need me to, it should not take long. I mean for the new strings. For the troubleshooting guide itself it may take a bit more time, it is quite detailed 👍 Amazing work @CAM-Gerlach |
If you mean the FAQ version, then it will get much more detailed still...Soon™ So the readme, contributing.md, etc. are indeed translated too? |
Nop, they aren't. I don't know if that's a good idea though. |
3968a28 to
d1b67e5
Compare
|
Rebased and pared down to just the core UI commits, minus the report error dialog, which will be included in #6154 along with the github issue template and auto-report enhancements, and moved the doc additions and improvements to #6084 . Further, deconflicted with #5346 , implemented basic tests for the menu item and troubleshooting URL resolution, and did some additional minor cleanup. Seems pretty much ready to go on my end, unless you'd like very basic tests (essentially that they display and close properly, since they have no other specific functionality to test) for the "about" and "crashed last session" dialogs. |
Adds a link and a short blurb regarding the new troubleshooting guide/FAQ in various appropriate places around the Spyder UI, including:
Also some associated cleanup and polishing of related error and help guidance text, to help better guide users.
Finally, also includes a
TROUBLESHOOTING.mddocument, along the lines ofCONTRIBUTING.mdwhich features a link and blurb to the full online guide/FAQ, as well as a few of the static sections that are likely to stay relatively unchanged, i.e, general troubleshooting tips and strategy, how to submit an issue, etc. Therefore, there is no need to hassle with maintaining it regularly, as it won't really become stale; and as its Markdown just like the wiki, it doesn't restrict compatibility whatsoever, and the relevant sections, if updated, can be easily copied and pasted in every once in a while if desired.Thanks!