4 ms·

You have described my experience with man pages, and in general with developer-written documentation. I think part of it is simply that a lot of devs struggle t

by otikik 3y ago

You have described my experience with man pages, and in general with developer-written documentation. I think part of it is simply that a lot of devs struggle to communicate what they know to people who don't already know what they know. I also suspect lack of interest is a big reason (writing the code is fun, writing the docs is boring).

jgalar 3y ago
In my experience, having to explain a software's design in plain English often reveals that some aspects were poorly thought-out in the first place.
- hinkley 3y ago
  ...which in turn triggers defensiveness in some people, making a bad situation worse.
sodapopcan 3y ago
A lot of the time the language in man pages fine, but it could be easily clarified for first-time readers with simple examples. What is it with that? It seems to be an unwritten rule that Man Pages Shalt Not Provide Examples. Is there a good reason for this is or is it a "secret club"-type thing or something else? EDIT: I "let me google that for you"'d myself and found this [0] right away which explains it, I guess. [0] https://unix.stackexchange.com/questions/306189/why-dont-man-pages-have-examples https://unix.stackexchange.com/questions/306189/why-dont-man...
psunavy03 3y ago
https://www.mountaingoatsoftware.com/blog/the-difference-between-a-professional-and-an-amateur https://www.mountaingoatsoftware.com/blog/the-difference-bet...
dspillett 3y ago
The trouble with a lot of technical documentation, particularly man-pages and in-tool command-line help, is that it usually seems written as a reference/reminder for people who know more-or-less what they are doing already. You can often work things out from a more standing start, but that sort of documentation isn't optimised for this so you have to work for your illucidation.
- vbezhenar 3y ago
  For popular technologies there are often books, tutorials and other introductory articles. Git certainly has enough information to start out without reading every manpage.
hiAndrewQuinn 3y ago
I think this is why `tldr` is so helpful as a starting point: It's crowdsourced from other people than the dev who need to just get things done.
- shadowgovt 3y ago
  The single biggest contribution StackOverflow made to documentation as a whole was to flip the script. Instead of the original developer of the material trying to prognosticate what questions people would have, people asked questions and either other users or the developer could answer them.
- jaynetics 3y ago
  As this might not be obvious to all, tldr is a crowdsourced man-page replacement, and also really useful when working with git. $ tldr git cherry-pick Apply the changes introduced by existing commits to the current branch. To apply changes to another branch, first use `git checkout` to switch to the desired branch. More information: <https://git-scm.com/docs/git-cherry-pick>. - Apply a commit to the current branch: git cherry-pick commit - Apply a range of commits to the current branch (see also `git rebase --onto`): git cherry-pick start_commit~..end_commit - Apply multiple (non-sequential) commits to the current branch: git cherry-pick commit_1 commit_2 - Add the changes of a commit to the working directory, without creating a commit: git cherry-pick -n commit
maw 3y ago
Believe it or not, I enjoy writing documentation. I imagine it as a competition between myself and an adversary with an uncooperative attitude, one who's prepared to act smarter, dumber, better informed and more ignorant than I am in order to to find gaps, inaccuracies, or ambiguities in the docs I write. It doesn't hurt that it improves my understanding of whatever it is that I'm documenting -- and where it could be improved.
- mbork_pl 3y ago
  This. I also like writing, but I love your description of technical writing as a (sort of) competition. Thanks!
- Tao3300 3y ago
  I write docs with my most terrifyingly dangerous adversary in mind: Future Me. His forgetfulness and capacity for ignorant destruction are unparalleled, at least that's what Past Me says.
kagakuninja 3y ago
In the '80s, all we had on UNIX were man pages, and I was able to glean useful info from them. Now they make my eyes glaze over, probably because every command now has 57 options. I just google how to do the thing.
- dboreham 3y ago
  There have never been "just man pages" in Unix. E.g. V7 had a number of papers (in troff format which could be rendered to the terminal or sent to the printer in finite time) that helped with understanding how to use the system (assuming you had more than the bare minimum disk space on your machine).
  - kagakuninja 3y ago
    Yes, and I bought some of those at the campus bookstore. What I meant was that if you want to know how to do a recursive grep or something, man was the main resource. There was no google or stack overflow.
nvy 3y ago
I basically never read man pages. In the overwhelming majority of cases you spend 20+ minutes reading the manual and it ends up not answering your question (or at least this is my experience) so you end up just doing a web search anyway.
bjornasm 3y ago
Same here. I feel like a majority of documentation and eapecially man pages are helpfull if you already know it, but just need a reminder.
PH95VuimJjqBqy 3y ago
That hasn't been my experience at all, I find man and info pages hugely helpful.
masto 3y ago
A lot of documentation is atrocious, particularly for newer stuff. But I kind of disagree on man pages. At least, when I first encountered Unix, it was on old SunOS machines, and I remember being impressed first that everything was documented, and second, that the documentation was comprehensive and useful. The things that make me most frustrated are when docs are missing, incomplete, or useless ("--foo: enables the foo option"). When it comes to man pages, at least in the good old days, I felt like I could always rely on them to cover all of the possible inputs, outputs, and errors, and to describe them, if not in the plainest language, in a way I could understand without being the author of the program. For example, I don't have much bad to say about https://shrubbery.net/solaris9ab/SUNWaman/hman1/ls.1.html https://shrubbery.net/solaris9ab/SUNWaman/hman1/ls.1.html

by otikik 3y ago

jgalar 3y ago

In my experience, having to explain a software's design in plain English often reveals that some aspects were poorly thought-out in the first place.

hinkley 3y ago
...which in turn triggers defensiveness in some people, making a bad situation worse.

sodapopcan 3y ago

A lot of the time the language in man pages fine, but it could be easily clarified for first-time readers with simple examples. What is it with that? It seems to be an unwritten rule that Man Pages Shalt Not Provide Examples. Is there a good reason for this is or is it a "secret club"-type thing or something else? EDIT: I "let me google that for you"'d myself and found this [0] right away which explains it, I guess. [0] https://unix.stackexchange.com/questions/306189/why-dont-man-pages-have-examples https://unix.stackexchange.com/questions/306189/why-dont-man...

psunavy03 3y ago

https://www.mountaingoatsoftware.com/blog/the-difference-between-a-professional-and-an-amateur https://www.mountaingoatsoftware.com/blog/the-difference-bet...

dspillett 3y ago

The trouble with a lot of technical documentation, particularly man-pages and in-tool command-line help, is that it usually seems written as a reference/reminder for people who know more-or-less what they are doing already. You can often work things out from a more standing start, but that sort of documentation isn't optimised for this so you have to work for your illucidation.

vbezhenar 3y ago
For popular technologies there are often books, tutorials and other introductory articles. Git certainly has enough information to start out without reading every manpage.

hiAndrewQuinn 3y ago

I think this is why `tldr` is so helpful as a starting point: It's crowdsourced from other people than the dev who need to just get things done.

shadowgovt 3y ago
The single biggest contribution StackOverflow made to documentation as a whole was to flip the script. Instead of the original developer of the material trying to prognosticate what questions people would have, people asked questions and either other users or the developer could answer them.
jaynetics 3y ago
As this might not be obvious to all, tldr is a crowdsourced man-page replacement, and also really useful when working with git. $ tldr git cherry-pick Apply the changes introduced by existing commits to the current branch. To apply changes to another branch, first use `git checkout` to switch to the desired branch. More information: <https://git-scm.com/docs/git-cherry-pick>. - Apply a commit to the current branch: git cherry-pick commit - Apply a range of commits to the current branch (see also `git rebase --onto`): git cherry-pick start_commit~..end_commit - Apply multiple (non-sequential) commits to the current branch: git cherry-pick commit_1 commit_2 - Add the changes of a commit to the working directory, without creating a commit: git cherry-pick -n commit

maw 3y ago

Believe it or not, I enjoy writing documentation. I imagine it as a competition between myself and an adversary with an uncooperative attitude, one who's prepared to act smarter, dumber, better informed and more ignorant than I am in order to to find gaps, inaccuracies, or ambiguities in the docs I write. It doesn't hurt that it improves my understanding of whatever it is that I'm documenting -- and where it could be improved.

mbork_pl 3y ago
This. I also like writing, but I love your description of technical writing as a (sort of) competition. Thanks!
Tao3300 3y ago
I write docs with my most terrifyingly dangerous adversary in mind: Future Me. His forgetfulness and capacity for ignorant destruction are unparalleled, at least that's what Past Me says.

kagakuninja 3y ago

In the '80s, all we had on UNIX were man pages, and I was able to glean useful info from them. Now they make my eyes glaze over, probably because every command now has 57 options. I just google how to do the thing.

dboreham 3y ago
There have never been "just man pages" in Unix. E.g. V7 had a number of papers (in troff format which could be rendered to the terminal or sent to the printer in finite time) that helped with understanding how to use the system (assuming you had more than the bare minimum disk space on your machine).
- kagakuninja 3y ago
  Yes, and I bought some of those at the campus bookstore. What I meant was that if you want to know how to do a recursive grep or something, man was the main resource. There was no google or stack overflow.

nvy 3y ago

I basically never read man pages. In the overwhelming majority of cases you spend 20+ minutes reading the manual and it ends up not answering your question (or at least this is my experience) so you end up just doing a web search anyway.

bjornasm 3y ago

Same here. I feel like a majority of documentation and eapecially man pages are helpfull if you already know it, but just need a reminder.

PH95VuimJjqBqy 3y ago

That hasn't been my experience at all, I find man and info pages hugely helpful.

masto 3y ago

A lot of documentation is atrocious, particularly for newer stuff. But I kind of disagree on man pages. At least, when I first encountered Unix, it was on old SunOS machines, and I remember being impressed first that everything was documented, and second, that the documentation was comprehensive and useful. The things that make me most frustrated are when docs are missing, incomplete, or useless ("--foo: enables the foo option"). When it comes to man pages, at least in the good old days, I felt like I could always rely on them to cover all of the possible inputs, outputs, and errors, and to describe them, if not in the plainest language, in a way I could understand without being the author of the program. For example, I don't have much bad to say about https://shrubbery.net/solaris9ab/SUNWaman/hman1/ls.1.html https://shrubbery.net/solaris9ab/SUNWaman/hman1/ls.1.html