Simplified and community-driven man pages
1–10 of 169 posts
Re: Simplified and community-driven man pages
#2This is a very interesting project. Years ago when I wanted to learn how to use Linux, my friend who was a system admin at the time just told me to read Man Pages. It was so overwhelming and confusing to say the least, it made me give up on Linux for a long while.
Times have changed and I will definitely love to contribute as well as recommend this project.
Re: Simplified and community-driven man pages
#3Re: Simplified and community-driven man pages
#4I'm not following. The most useful thing on first read (and at other times) of man pages are the examples section. Frequently this section is pretty bare which is unfortunate. We should fix that. Yep with all of that.
npm install a thing with multiple clients. Um, huh? Where did that come from? At best now we have 2 competing man page systems, one for the "complete" information and one for the examples section? This is crazy, surely? You're not going to be able to stop using man pages! A replacement that can't be a replacement.
But sadly the examples themselves will probably have licensing problems to be able to be incorporated as documentation patches to the man pages - I hope I turn out to be wrong about that.
Re: Simplified and community-driven man pages
#5This is a very interesting project. Years ago when I wanted to learn how to use Linux, my friend who was a system admin at the time just told me to read Man Pages. It was so overwhelming and confusing to say the least, it made me give up on Linux for a long while. Times have changed and I will definitely love to contribute as well as recommend this project.
I've been using Linux for twenty years and have maybe spent two hours reading man pages. Man pages seem to be written by engineers that honestly wrote them like it was code. It's dense material and assumes you can decipher it.
Since the days of Alta Vista and webcrawler. And even with Google, I skip the first link (man pages) and find a better explanation
Re: Simplified and community-driven man pages
#6The main thing about man pages is that it is a "manual": reference material for people who already know the basics.
If you are just getting started, don't read the man pages, but read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books. Those will generally be tailored to beginners, including features such as discussions of unifying themes between different commands, historical references and more beginner-friendly organization. Beginners don't need to know all the details at first (which are what the man pages provide), but just the big picture.
Re: Simplified and community-driven man pages
#7The main thing about man pages is that it is a "manual": reference material for people who already know the basics. If you are just getting started, don't read the man pages, but read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books. Those will generally be tailored to beginners, including features such as discussions of unifying themes between different commands, historical references and…
What I like about this though is it's easy to forget the basic options of a command you haven't used in several months. Having the most common use cases at the top of the man page would save a lot of time than digging through some textbook.
Re: Simplified and community-driven man pages
#8The main thing about man pages is that it is a "manual": reference material for people who already know the basics. If you are just getting started, don't read the man pages, but read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books. Those will generally be tailored to beginners, including features such as discussions of unifying themes between different commands, historical references and…
Sure, but what usually happens is you sit down at a Unix command line for the first time and have no idea what to do. You ask someone (after seeing that `help` does nothing useful), and they tell you "use 'man' instead of 'help'". And you have no idea why, but you try it and it kind of helps and is better than nothing. You don't have any idea you should `read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books.` (Likewise, you wouldn't know at first to install something like this, either.)
Re: Simplified and community-driven man pages
#9Man pages feel like RFCs for tools. They have a lot of information about how to use them but they're sometimes pretty difficult to parse. I'm really excited about this project. Whenever I don't know how to use a tool I look at a StackOverflow answer for an example. I've been doing this for as long as I can remember. I'm glad there is a dedicated service for this now.
Re: Simplified and community-driven man pages
#10There are a bunch of projects like this, check out `cheat` and `bropages` as well.