Since I’ve become more active in trying to help in the Support and Help category, I cannot help but notice a certain amount of verbose “boiler plate” text. For instance, the first thing many helping members ask, goes something like this:
And then the OP pastes that into a blockquote block, most of the time at least. But, since it’s more typing effort to explain, how to put it in pre-formatted blocks, preferably within a “hide details” element, what are they supposed to do?
Case in point:
So let me propose a simple helper tool – just a few lines of shell magic – that would enable us to just say:
And the script runs that command, tees it to the terminal for transparency, wraps it in markdown and/or BBCode and pipes it to the clipboard.
Of course this may need some additional helper installation; I don’t think wl-copy from the wl-clipboard package is installed by default. And it’s tied to wayland, so what’s the equivalent again for X11? xsel?
Are you asking for my thoughts? Really? Well, you asked for it.
It is not human. Screen loads of diagnostic text which does not diagnose the problem is blinding someone with science. I scroll past all that stuff. I look for human communication. What did you do? What did you see? What choices did you make? Was there a Windows update?
I remember when I was using Win98 and I got an Error 45 message. It was something like that. I researched what error 45 was and all I found was: Error 45 is an error message. Well, thank you for nothing.
I choose Ubuntu because I read in computer magazines that Ubuntu was for humans. It was human friendly. I did not have to be a geek or a nerd to install and use Ubuntu.
Some people do want to know the ins and outs of computer operating systems. Others just want the OS to work so that they can use it to do stuff.
How to help the humans using Ubuntu when something goes wrong? With commands that produce screens loads of text which lack any explanation of what it all means? It is great for the elites among us but that does not help me to help the person.
Of course we could all be given the training that would turn us into Help Desk staff complete with a very large document listing all the things that go wrong and what to do to fix it.
Since the old Ubuntu Forums was merged here into the Support and Help category a lot of thought and time has gone into trying to figure out the best way to help users of all levels.
Thus, the support template was born (amongst other ideas).
However, despite that guide in Start Here that explains how to use it or experienced users asking for output it is a best effort attempt.
Some users take advantage, others not.
Perhaps the next time you see a support topic that would benefit from this approach, you can ask the user to test it out.
Would be interesting to see the response and output.
It’s the easiest way to get to the bottom of things.
That becomes tedious very quickly and still may get you nowhere, for it starts with explaining technical stuff to laymen; consider it a translation/language barrier, as if supportees were foreigners. They run away screaming before you found enough common language to even begin to understand the problem cause.
The goto tool for diagnosing things is journalctl, for it hold all the logs. We can iterate from there.
I’d really like to try, but I can’t see a place to put it for download. And I don’t think, explaining how to create a shell script, paste that code, chmod +x etc. would help.
Why not keep it simple? Here in discourse - why not instruct users to open a new line, press the button </> and enter/paste data in the created field?
If you really want to change something: why not forward shell output to a file and create a function in discourse which accepts such file and puts its content with formatting into the editor? Similar to uploading images, but for text files.
I don’t consider that simple, because it’s tedious to explain, tedious to get right and error prone. Especially wrapping it all in “Hide Details” is vital, so readers can keep their sanity, instead of being overwhelmed with walls of console output; and for that there should be a proper “Summary” text, which reflects the command. Or would you immediately know which commands produced these lisitings? Also note, how the first listing is code wrapped in “Hide details”, whereas the rest are just “Hide details” and normal text; as I said, error prone. And we haven’t even talked about very long output, which is a pain to copy manually, and it might be truncated due to limited scroll buffers of terminals.
The goal is to make this as easy as possible, for all involved.
I am not in a position to do that. Also, If we had file attachments formatting would be unnecessary.
I don’t think so - wrapping in “Hide Details” depends on length of text. And if the inserted text is fundamental for helping it might get tedious to always need to expand hidden sections. Furthermore “Preformatted text” adds scrolling by itself if contained text is longer …
One line of instruction isn’t simple? How many lines will you need to explain the user install and usage of your script?
My opinion: making information collection more complex for the user isn’t making it simplier …
Of course, but it adds complexity to the script, to switch between long and short output. Most of the time output is several lines long.
Now you’re just fishing for excuses, not to do this.
And once there are multiple listings, the auto-scrolling in code listings can come back to bite you or any other reader, because your mouse pointer might be in the wrong place. I’d rather open one too many “Details” sections than not having them at all. The code listings are important information, but they should not take center stage and go away, once read, so one can read the rest of the post while retaining much more of the context.
In the end it should be a win, because they won’t have to remember to do this, that and the other thing before jumping through some moving burning hoops to get a readable help request. I don’t want to read such badly formatted posts all the time, and I don’t want to nag new members too much, so this seems the better option. Just direct people to that script. If we can ask them to run arbitrary shell commands, what’s two more? Less annoyed helpers can focus on what really matters.
Thanks, I actually didn’t know that. Discourse is still relatively new to me. But then what would be the real gain? We’d still have to explain how to create said files, find and upload them. For instance, command >output.txt puts the files in the home directory, most probably, because that’s where the shell is spawned. So now we have to explain where to find that file, and the user must open an app, do some eyeballing etc.
With my script, OTOH, they’d be done after running the command. From there it’s just Ctrl-V in the Discourse editor. Plus, all the “administrative” tasks are done, i.e. the Details title being set to the command that was run.
On a more general note, this is actually why computers exist in the first place, free humans from tedious error prone tasks that a machine can do better. And look how much better they can do that; that script is rather tiny, but provides a lot of leverage. Ever Details block that is actually there and doesn’t need to be manually edited to give it a title is a win.
With a new discourse plugin It might work like this:
Make it command > ~/output.txt and the file is always in users home. Start ‘Files’ (or another file browser) and it will usually open in users home. File found. Pick file and drag it on discourse input field. Done.
That wasn’t exactly the point; people are lazy and will forget to type ~, on either side of the aisle.
See? That is after the command was run. And you’d have to be more elaborate than that. Again, with that script: Ctrl-V → done. Plus, “File found.” and “Pick file and drag it on discourse input field.”, are manual tasks which don’t add any value.
That’s a pretty big downside, because that disqualifies any post, which links to to the pastebin, from being useful after the expiration date. I have seen those, and they are the worst, because a vital piece of the info is missing.
But it’s also kind irrelevant for this script. Both approaches can coexist, as they should, IMHO; mix and match as the one using, or the one suggesting use of, the tools sees fit.
And yet I find it far simpler to explain than your OP, which even as a seasoned user I found tricky. I couldn’t find how to install get-output — how would we expect a newcomer to figure that out?
Gerhard’s suggestion is far simpler, and only needs to be taught once to a user.
The OP is just a PoC, it’s a little more fleshed out here.
The point is that explaining once how to do that will keep paying dividends, especially since there is a benefit to both side. You’ll have less explaining to do and the supportee has less to do. I find it rather tedious to do all that stuff manually. When it’s repetitive and simple leg work, there usually is a simple way to make the machine take that off your hands.
BTW, that’s a rather strange reason. Just look a this new support request. The first image is ~280KiB and only shows a single error.
By comparison journalctl -b -p warning on this my local machine is just ~180KiB, while spanning ~1400 messages. And that includes warnings; just the errors are 28 messages for a total of less than 4KiB.
