README in markdown

[acalvino4]

Feature request for the readme to be updated into markdown. Will make reading the documentations oodles easier. Honestly I almost didn't take this project seriously because I couldn't find easy-to-read docs (though I'm glad I tried it out). This may have been pedantic 10 years ago, I don't know, but it's 2022 and markdown is kinda just expected for a readme.

While at editing the readme, would probably be worth noting installation instructions for major distros, such as apt install pdsh. Might seem obvious to try that, but I've had coworkers try things the more complex way bc that's the instructions they come across first, and I suspect they are not alone.

[smemsh]

Just to offer a countervailing opinion, the README and INSTALL seem totally fine for me, they've been suitable for the past couple decades. Markdown and use of long line paragraphs would be a regression (but if the lines were kept wrapped, markdown wouldn't change much). I must have missed the memo about markdown being required for readmes. Plain text files wrapped at 72 columns are still the best way to read things, at least on my terminal.

Package installation instructions would seem self-evident as you suggest -- ie check your distro first to see if it has a package, like with any software -- if you don't want to build it.

[grondo]

FWIW, I'd be fine with a PR that converts the README to markdown, as long as we keep the other formatting and no lines longer than 78 columns as @smemsh suggests. The file should still be readable as text on the console.

A small note that pdsh is (probably) in most distros, and package installation is preferred, but "instructions to compile from source are included below" would be fine too.

Happy to approve a PR is someone wants to tackle it 😉

[acalvino4]

@smemsh I guess everyone's opinion is valid, and this certainly is an opinion thing... but yeah I guess we just disagree on the matter. I'm not suggesting that md is a requirement in any official way - just that it's a general expectation, and that (as far as I can tell) most people prefer it.

Anyway I decided to go with clustershell at the moment, so I guess I am now indifferent to whatever people do here. If it's helpful to maintainers to know, my reasons for not using this tool are

• As far as I can tell, no ability to configure options via a config file (or lack of documentation about it, which is just as bad)
• The use of rsh by default (I know this is configurable with an environment variable, but I'm weary about someone on my team installing and not setting that in /etc/profile)
• Documentation is non-intuitive to navigate and hard to visually parse (which in my opinion is due to the use of plain text). If someone replies that "all you have to do is crawl around the repo till you find it", my response is that it's 2022 and while I can figure that out, there are better systems (like the docs of clustershell, or the markdown readme's of every other repo on github) that are easier, so I'd rather not go through the trouble.
• No evident documentation on configuring groups (I see references to the 'genders' module, but no instructions on how to use it)