this post was submitted on 15 Jul 2024
325 points (99.1% liked)
Programming
17342 readers
263 users here now
Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Rules
- Follow the programming.dev instance rules
- Keep content related to programming in some way
- If you're posting long videos try to add in some form of tldr for those who don't want to watch videos
Wormhole
Follow the wormhole through a path of communities !webdev@programming.dev
founded 1 year ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
If not code or documentation contributions, then well-written bug reports. Seriously, the quality of bug reports sometimes leaves a lot to be desired. And I don't necessarily mean a full back-trace attached -- and please, if you ever send a back-trace, copy-and-paste the text, never a screenshot -- but just details like: system details, OS, version, step-by-step instructions to reproduce that a non-coder could also understand, plus what you expected to happen versus what actually happened.
This stuff (usually) comes naturally to programmers and engineers, but users don't necessarily see things this way. I sometimes think bug reports need to adopt a "so tell me what happened?" approach, where reporters are encouraged to describe free-form what they think of the software, then providing the specific details that developers need. That at least would collect all the relevant details, plus extra details that no developers thought to ask.
Even just having folks that help gather and distill details from user reporters on a forum is easing a burden off of developers, and that effort should be welcomed by any competently-organized project. Many projects already have a template for reports, although it often gets mistaken for boilerplate. Helping reports recognize that they need to fill in all the details is a useful activity that isn't code or docs.
I think, this may be one of the rare cases where use of LLMs may be reasonable. Help user structure their report, then call for a human
The problem I have with bug reports for things like docker containers (I will just use that example for now) is again documentation... I get that most people make really bad "it broke, fix it now" kind of reports with no detail, but unless you actually dig into and know the code, there is often almost no debugging documentation (github issue templates help with that when the devs make one)
Where are the logs? If you refuse to use the docker standard of pushing logs through the log api, don't respect the LOG_LEVEL environment variable, errors are non-descriptive, and don't provide documentation to where your logs are stored, how the hell can you expect users to provide relevant logs??
I have run into dozens of pretty big projects that fail with 0 log output and there is 0 log documentation and then the dev auto closes the issue because "not enough logs to help." The only way to find the logs is to find an old issue where the dev has laid out where the relevant logs are, like WTF? No I am not going to spend an hour looking in every single part of the undocumented directory structure to see if there happen to be logs in there. Use the standard, document your log locations and what they log (no 3ch9qjV7.log is not descriptive enough), or don't complain about not being able to help without logs.