Docs bugs not supported; docs bugs exist

[Bujiraso]

A preface

I see there's lots of efforts on the GitHub project side to curb folks from making low-effort issues, but this has bled into blocking docs bugs. I've opened this discussion because of these pains points, but I'll quip that it's not a 'possible' issue that I have, it's a definite issue. 😋

Docs issues should be supported: docs bugs are software bugs

The GitHub Issue form for a bug is quite in-depth. That's probably good when filing a bug on the software as executed, but it's pretty harmful to the process when filing a docs bug. Docs bugs don't always have software versions, probably don't have configs, and certainly don't depend on whether or not someone is on Wayland or what have you -- I might be on Wayland, yes, but only on the website 🙃

I actually haven't even built rofi yet, because I'm just reading and I've hit a blocker. So...

Issue 1: there should be a "Docs Issue" type

The doc bug itself RESOLVED: user error

The steps at https://davatorium.github.io/rofi/INSTALL/ detail a step to mkdir build and then cd into it and run ../configure but there is no configure.
Perhaps the missing documentation step is a call to autoconf. Trivially calling it here results in errors, and the resultant configure step does not work.

Issue 2: The autoconf install docs need a bit of review

If it's expected that we simply know autoconf already, then the steps can be omitted. Otherwise, there's a step necessary to generate a proper configure script.

that's it!

happy coding! ⌨️

[DaveDavenport]

On the bug itself

Can you provide more information? what is the actual code you want to try to install, there are several options.
(git checkout, release from the release page, the auto attached source code from github on the release tag).
This would be needed to review the documentation? it is currently not clear what is lacking.

From the description of your issue it can be two things:

• You are trying to build a git checkout using the 'release' build instructions. Please use the instructions
  install a checkout from git. This has all the steps, including the steps to generate configure.
• You downloaded the (broken) auto-attached code checkout that github adds to each release, instead of the actual source we provided. This one https://github.com/davatorium/rofi/releases/download/1.7.5/rofi-1.7.5.tar.gz should work according to the build release instructions.
  The github generated download that we cannot remove can be compiled using the 'checkout from git' instructions.

I agree this should be added to the install instruction.

but I'll quip that it's not a 'possible' issue that I have, it's a definite issue. 😋

Hence the () around possible.

but this has bled into blocking docs bugs.

If you check the history in discussion/issues/merge request you see that I am not trying to block documentation feedback/support.. I often have asked for support with it, as I am aware of my shortcomings in this area.
I think it is a good idea to add a separate entry for documentation! I have not thought of this before, thanks.

I do find the tone you strike here pretty negative and not very productive. Instead of suggesting to make a separate Documentation category in the issue tracker, you directly strike a negative tone, make a lot of assumptions, make invalid quips, call it harmful, etc.

[Bujiraso]

You are trying to build a git checkout using the 'release' build instructions. Please use the instructions
install a checkout from git. This has all the steps, including the steps to generate configure.

This is likely my issue

I do find the tone you strike here pretty negative and not very productive. Instead of suggesting to make a separate Documentation category in the issue tracker, you directly strike a negative tone, make a lot of assumptions, make invalid quips, call it harmful, etc.

My understanding of what I had done was to actually just to make the suggestion, not to strike a negative tone and be unproductive. I can definitely take your feedback and hopefully modify how I write discussions to any project in the future, as it's good feedback you give. We disagree about the intention behind my words, such as harmful or whether or not my quips were supposed to be sharp or playful -- there really was no ill intent there and this was my attempt to strike a positive tone. I do not have this skill. Ultimately, it's not worth diving into since I appreciate your feedback that it wasn't received how I intended it and will modify how I sound accordingly as best as I can in the future. The existing post will remain as is for other learners.

I'll have another try at the building from a checkout, thanks for your reply!

[DaveDavenport]

I will admit, with the often lazy, demanding, very negative posts/e-mails/dms down to person attacks, I might be biased to read things in a negative light. My apologies.

I think my biggest feedback (also to myself) is not to make assumptions. Things very often are there for a good reason, even if you might not directly see this. For example:

• Docs bugs don't always have software versions -> False, The majority of the documentation is very closely linked to versions, including installation/compilation documentation. It is better to request a version for the 98% it is relevant for, then have it optional (and not filled in most of the time) for the 2% it might not.
• Docs bugs don't always have software versions -> Having a rofi version linked in an issue help place the issue in time. If somebody looks for it later. e.g. if he/she sees the documentation issue reported on 1.7.3 and fixed quickly after, he/she knows to maybe look in newer documentation for the answer, or that this is not the same issue.
• certainly don't depend on whether or not someone is on Wayland -> It does, rofi on wayland is a fork of this project and there might be differences between these versions.
  etc.

Not sure if you saw, but I did add a special documentation issue template to the tracker. Thanks again for the suggestion. link

[Bujiraso]

😅 I'm happy to share 50% burden -- we can all use to improve.

These bullet points are good tips and good points. I clearly made the false assertions on those above.

The new issue type looks good! 🎉 🚀