hwinfo: add page

[mmahmoudian]

• The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
• The page(s) have at most 8 examples.
• The page description(s) have links to documentation or a homepage.
• The page(s) follow the content guidelines.
• The PR title conforms to the recommended templates.
• Version of the command being documented (if known): 23.2

[CLAassistant]

All committers have signed the CLA.

[tldr-bot]

The build for this PR failed with the following error(s):

pages/linux/hwinfo.md:3: TLDR003 Descriptions should start with a capital letter
pages/linux/hwinfo.md:3: TLDR004 Command descriptions should end in a period
pages/linux/hwinfo.md:4: TLDR003 Descriptions should start with a capital letter

Please fix the error(s) and push again.

[mmahmoudian]

This is awkward! Your tldr-bot is enforcing things that are not in the guideline !! I just broke the line at 80 character mark and still am following the contribution guideline.

Here are the reason why all these thrown errors are nonsensical:

• pages/linux/hwinfo.md:3: TLDR003 Descriptions should start with a capital letter
  • The name of the command is hwinfo, why should I capitalize the name?! Yes, I can change it to "This software..." but that is just rambling and adds zero value and clarity!
• pages/linux/hwinfo.md:3: TLDR004 Command descriptions should end in a period
  • It does not end with a fullstop because it is in the middle of the sentence.
• pages/linux/hwinfo.md:4: TLDR003 Descriptions should start with a capital letter
  • same as the previous point!

I will change it, but these surprises that are not in the guideline is nauseating when happens!! These nonsensical checks are a surprise! You should be extra transparent about this up front. I have invested time and efforts in improving the tldr database and helping others, but why should I have to put up with all these hiccups that are creeping out of nowhere! These for sure have left a bad impression, and will affect my view about contributing to this project in future! Transparency is a big key factor in FLOSS, and these out-of-nowhere paper-cut errors are violating that transparency.

[mmahmoudian]

Thanks for the suggestions. I disagree with the comment about description. I think the description is now terrible and does not make sense. But nonetheless I committed the changes you suggested.

Anyways, the lack of transparency is still a big thing in this project dues to this tldr-bot thingy. Maintainers perhaps need to do something about that a.s.a.p .

[Managor]

If you see things to correct in the guidelines or with the bot, please open an issue in the tracker so that it's not forgotten after this PR closes.

[kbdharun]

Your tldr-bot is enforcing things that are not in the guideline !! I just broke the line at 80 character mark and still am following the contribution guideline.

We don't follow the conventional 80-character limit, our pages allow descriptions with up to 250 characters (after which you will get a warning from tldr bot). The clients wrap these characters (words) according to the terminal's size.

The name of the command is hwinfo, why should I capitalize the name?! Yes, I can change it to "This software..." but that is just rambling and adds zero value and clarity!

If it's a command you can use Markdown's backticks to highlight it (`). We encourage having a descriptive page description. That's why it encourages capitalization.

It does not end with a fullstop because it is in the middle of the sentence.

As mentioned before, you can write the sentence continuously. As tldr clients will consider subsequent > as a separate point.

Information about lining and tldr-lint is available in the style guide which is already mentioned in the contributors guide.

I will change it, but these surprises that are not in the guideline is nauseating when happens!! These nonsensical checks are a surprise! You should be extra transparent about this up front. I have invested time and efforts in improving the tldr database and helping others, but why should I have to put up with all these hiccups that are creeping out of nowhere! These for sure have left a bad impression, and will affect my view about contributing to this project in future! Transparency is a big key factor in FLOSS, and these out-of-nowhere paper-cut errors are violating that transparency.

I highly appreciate you spending time to improve tldr, thanks. Information about the layout and other rules are indeed documented in a generalized manner on the style guide and tldr-bot just runs tldr-lint (which you can run locally too to test the changes). I would suggest checking out similar pages when you stumble on an error, that would help you resolve it most of the time. If you need additional assistance with your PRs feel free to ask us in our chatroom.

Anyways, the lack of transparency is still a big thing in this project dues to this tldr-bot thingy. Maintainers perhaps need to do something about that a.s.a.p .

tldr-bot's addition was done after a public discussion on both GitHub and the chatroom with acknowledgement from other maintainers and the community (it was added after your last contribution, that's why it might be new to you but tldr-lint was present before too).

[kbdharun]

LGTM, Thanks for your contribution.

[mmahmoudian]

This is ridiculous! I made a PR, then the bot started some baseless nonsense and ultimately you butchered the PR? Why on earth did you even change the URL? The tldr documentation states:

On the More information line, prefer linking to the author's provided documentation.

When not available, use https://manned.org as the default fallback.

Amd the original repo of the software contained way more information that that manned.org website you changed it to. Why did you even change my PR when it is in accordance with your guidelines?!??? It seems you yourself don't know your own guidelines!

Preposterous! At least you could write your reasoning rather than forcing your opinion without any explanation!

[Managor]

Correct me if I'm wrong, but to me the author's documentation page doesn't contain much info on what options can be used with the program. Only a cursory look at what it can do.

[mmahmoudian]

Correct me if I'm wrong, but to me the author's documentation page doesn't contain much info on what options can be used with the program

the tldr guidelines does not specify that the URL should contain the content of the manpage! it states "linking to the author's provided documentation" which the link I provided was exactly the "author's provided documentation".

That said, by doing these changes without explanation and justification, you violated Project governance principles.

Principal 2 states "Avoid making assumptions about the others' intentions, and make your own intentions clear. When in doubt, provide additional context, or ask for clarification." ---> and yet you didn't provide any context and forced your own preference, although as i explained above the original text was on par with the contribution guidelines.

Principal 4 states "all interested members of the community are welcome to voice their thoughts, and incompatible positions will ideally be resolved with participants either agreeing with the final decision, or voluntarily consenting to accept it" ---> which was violated because the modification was forced to this PR without discussion or even allowing some room for discussion!!

[kbdharun]

@mmahmoudian Thanks 🙏 for your honest feedback.

We strive for contributors like you who give constructive feedback and raise their concerns with us.

I would like to apologise for the whole situation here, I didn't follow the intended duration to wait for the author's feedback before applying the change (and it was merged after the changes were applied). Hacktoberfest starts tomorrow and during the month of October, we get hundreds of PRs so we tend to update and merge old PRs that are almost GTG as we don't want it to go stale.

I will ensure a similar case won't occur in the future. If you would like to modify any contents of the page, feel free to create a new PR.

Addressing your feedback I would like to propose/work on a few things

Your tldr-bot is enforcing things that are not in the guideline !! I just broke the line at 80 character mark and still am following the contribution guideline.

Starting with your tldr-bot concern, it isn't going away anytime soon as it eases the reviewing process for maintainers and also helps us maintain the quality of pages.

I agree the messages might seem a bit bland or even lack information on how to fix it. So I would like to work on adding case-by-case documentation on how to fix each error code and how to fix it on https://github.com/tldr-pages/tldr-lint README and maybe even add it to the tldr-lint package too.

The current tldr-bot output running tldr-lint is this:

I will discuss with the person hosting tldr-bot to see how to improve it and make it refer to our chatroom if an author needs additional assistance.

This is ridiculous! I made a PR, then the bot started some baseless nonsense and ultimately you butchered the PR? Why on earth did you even change the URL? The tldr documentation states:

On the More information line, prefer linking to the author's provided documentation.

When not available, use https://manned.org/ as the default fallback.

Amd the original repo of the software contained way more information that that manned.org website you changed it to. Why did you even change my PR when it is in accordance with your guidelines?!??? It seems you yourself don't know your own guidelines

Once again I apologise for applying the change without an explanation of why we did it. The documentation about "More information" links hasn't been updated in a while.

We generally prefer using the command line reference docs or man page in more information links as we target both technical and non-technical users. In this case, the author's repository README, didn't reference to the man page for command line reference. And you need to browse through the directories to find this unrendered man page. That's why referred to manned.

Now that I look back through the conversation and the page since this is an OpenSUSE project we can refer to https://manpages.opensuse.org/Tumbleweed/hwinfo/hwinfo.8.en.html for the official man page. I will create a PR to update the link and also to update the information in the style guide.

Thanks for the suggestions. I disagree with the comment about description. I think the description is now terrible and does not make sense. But nonetheless I committed the changes you suggested.

Anyways, the lack of transparency is still a big thing in this project dues to this tldr-bot thingy. Maintainers perhaps need to do something about that a.s.a.p .

Addressing your initial comment again, we indeed prefer imperative mode but we do suggest having a descriptive description. Some of the suggestions like info -> information aren't documented in the style guide as we decide on a case-by-case basis for example in a command that has a long description we use info instead of information to not cross the character limit. Whereas in this case, since the character description is small I suggested going with a longer version instead.

you even change my PR when it is in accordance with your guidelines?!??? It seems you yourself don't know your own guidelines!

Preposterous! At least you could write your reasoning rather than forcing your opinion without any explanation!

I just want to clarify that the maintainers are aware of the guidelines and they are active contributors themselves prior to becoming a maintainer. We do provide feedback and additional information on suggested changes, especially to new contributors. We didn't do it in this case as you were one of the existing contributors.

It would almost be impossible to force maintainers to provide information on each and every suggestion they make as we are all volunteers who maintain tldr in our free time outside work or classes. I would like you to think from the maintainer's perspective too.

These for sure have left a bad impression, and will affect my view about contributing to this project in future! Transparency is a big key factor in FLOSS, and these out-of-nowhere paper-cut errors are violating that transparency.

We strive to be transparent about the whole process, and in cases we aren't we are willing to address the community's feedback/apologise and move on with our goal to provide easy-to-understand cheatsheets for commands in any language.

Thanks for your contributions so far, I hope the current situation doesn't affect you. I would love to see your contributions in future and maybe even review them (if I stick around 😄 ).

[Managor]

Also yeah, I apologize for not thanking you for your contribution when merging. I'm new to this. All contributions are valuable to us.
The mentality I personally take to contributing is that I create a rough draft of the command and then the people who have done maintaining longer than me do a lot of minor corrections to the formatting to be more uniform with the rest of the pages. Uniformity is extremely important for guides like these.

[kbdharun]

Just now noticed this https://fosstodon.org/@Mehrad/111150673122780591. I know you didn't specify the project name or the individuals (people can still look it up) but instead of making comments like this on other platforms as a fellow maintainer, I would suggest letting us know when you think we are wrong (like you already did here). There are better ways to resolve situations like this, especially in FOSS. Comments like this affect both the project and the individual involved in the long run (even when I or the other maintainers here aren't part of the project) which as someone involved in FOSS like you might already know.

Yes some of us might be younger than you that doesn't make us immature. We do make mistakes and are willing to correct them.

[mmahmoudian]

@kbdharun

I would suggest letting us know when you think we are wrong (like you already did here). There are better ways to resolve situations like this, especially in FOSS.

So I did. I wrote lengthy text giving constructive criticism with clear explanation of what was wrong and what should have been done instead. Not only you didn't address the violation of your own principals, but you didn't even mention what actionable plan you have to mitigate the issue and prevent it from happening again. After all, I played by the book (your book), and in return I got this mess.

You said your documentation is out dated, you didn't provide context because I have contributed before, and you said you have merged this PR and other in hurry due to hacktober fest! How these should make me feel better or less offended? You violated your own rules, your own terms, your own principals. That simple. Instead of covering up for others mistake, take an action, make a step forward.

Yes some of us might be younger than you that doesn't make us immature. We do make mistakes and are willing to correct them.

No, although age and maturity have some positive Pearson correlation, one does not guarantee the other (the famous "correlation doesn't mean causation"). The behavior on the other hand shows maturity. As you stated yourself, mistakes have been done, fair enough, but an apology does not make it water under the bridge. What actions are you going to take to address these mistakes? Show to the community that this project is learning from its mistakes and can be improved.

Since you are treating me like a dev, I treat you like one. So here are my suggestions:

1. Fix that bot and tldr-lint to be 1 to 1 on par with your guidelines.
2. Update your documentations (if it is not in your guidelines, it should not be enforced
3. Tell people up front that any PR will go through some manual changes (transparency) and this does not mean their PR is BS
4. Be welcoming. Accept slightly sub-optimal PRs, and then make a quick fix for it later.
5. When suggesting a change always write the reasoning. This is because 1) people tend to forget 2) your guidelines are not static and are subject to change. No more excuses.

For instance, one of you people here changed --argument=value to --argument value without realizing that these two can be parsed differently, and blindly changing that is wrong. Yes, the convention is that they are interchangeable methods, but it depends on the arg parser library. It is the same convention that long arguments should start with double -, but the GNU find doesn't follow that, or the convention that -nw means -n - w, but GNU Emacs doesn't follow that.

Also, a friendly advice: All these tiny changes by maintainers of this project have inflated their "contribution stats", although there is bot much added value. This is a good trick, but it just create an incentive for junior maintainers to do insignificant nit-picky change here and there and "climb up the ladder" in the contribution page. Don't let such ill practice in your project.

About my social media post: is any of it wrong or unjustified? No it is not. It is the ground truth. If you want to do a good PR (public relation), take some measures to address all these flaws you yourself agreed to. Making a mistake is not as bad letting them happen again. Out of curiosity I will remove the Mastodon post.

This will be my last comment here as I'm clearly sick of this.

[SethFalco]

The name of the command is hwinfo, why should I capitalize the name?! Yes, I can change it to "This software..." but that is just rambling and adds zero value and clarity!

You were not asked to strictly capitalize the name, just to ensure the description starts with an uppercase character. I agree with removing hwinfo is used to which was unnecessarily verbose for a tl;dr.

I have invested time and efforts in improving the tldr database and helping others, but why should I have to put up with all these hiccups that are creeping out of nowhere!

These hiccups did not creep out of nowhere. They came up in our CI pipeline, and are intended to help contributors make quality contributions. Do you write the same complaints to every other project that doesn't list all linting rules enabled in their contribution guide?

Also, based on your attitude, you need to understand that just because you invested your time in it, doesn't automatically mean everyone will appreciate how it was done.

A contribution is only valuable if others attribute value to it. This was a nice PR overall, but investing your time in it does not inherently give it value.

Transparency is a big key factor in FLOSS, and these out-of-nowhere paper-cut errors are violating that transparency.

What lack of transparency? We try to be as clear as we can, and definitely can do better. But you got feedback on your PR right away…

You're welcome to help us improve our documentation, but disruptively complaining about it isn't a worthwhile investment of your time. Many open-sourcerers make reading and contributing to the contribution guide part of their workflow, see:

https://github.com/tldr-pages/tldr/commits/main/CONTRIBUTING.md

I think the description is now terrible

Please consider how people treat you vs how you treat others. When someone gives your PR feedback, that's someone contributing to your changes.

You aren't giving other contributors the same respect you expect from them. Insulting other people's work does not help us improve things, at least be constructive.

do something about that a.s.a.p

There is no such thing as ASAP in volunteer run projects, but contributions are always welcome.

Why on earth did you even change the URL?

Because the page you originally linked to didn't clearly state how to use the command.

project have inflated their "contribution stats", although

No, it did not. We squash and merge in this repository, so everything was compressed into one commit. People should be credited for their contributions, the same as you. That includes if someone contributes to someone's contribution, which is ultimately what everyone here is doing.

Nitpicky changes are not something to shame, be it from a maintainer or contributor. This is how we maintain the quality of tldr-pages. I respect everyone who takes time out of their day to resolve typos, omit redundant words, or reword sentences. They took the time to think about the user experience of the reader, rather than spew text on a screen, which is invaluable.

---

I ask kindly that in future, you be more compassionate when you communicate with volunteers.

[kbdharun]

Edit. The progress is now being tracked in a separate issue #11146.

[kbdharun]

This is all I can compile for things to document, I will start working on all the above things in a phased manner in the forthcoming days/weeks.