THIS. I feel like linux man pages are as useful as an Analytical mechanics textbook for someone who just wants to drive. Like yes, sure, it’s amazing we have such a detailed documentation but for God’s sake just introduce basic usages first
but for God’s sake just introduce basic usages first
And include practical examples!
Much easier to figure out the correct formatting of some command by just seeing the formatting used properly!
It’s also a great place to sneakily introduce the most common and useful ways to use the command, by including those as the examples! (Are you documenting, say, a command to compress images and documents, and even though most people never use it for video, you want people to know that it works with some video formats as well? Then include compressing .mp4 file as one of your example commands!)
THIS. I feel like linux
manpages are as useful as an Analytical mechanics textbook for someone who just wants to drive. Like yes, sure, it’s amazing we have such a detailed documentation but for God’s sake just introduce basic usages firstAnd include practical examples!
Much easier to figure out the correct formatting of some command by just seeing the formatting used properly!
It’s also a great place to sneakily introduce the most common and useful ways to use the command, by including those as the examples! (Are you documenting, say, a command to compress images and documents, and even though most people never use it for video, you want people to know that it works with some video formats as well? Then include compressing .mp4 file as one of your example commands!)