3 ms·

Heh. Should have told you to go read the FreeBSD manual. That’s the first OS that made sense to me because of it. I actually ended up translating parts of it to

Heh. Should have told you to go read the FreeBSD manual. That’s the first OS that made sense to me because of it. I actually ended up translating parts of it to Russian because I enjoyed it so much. NetBSD was the first thing I got running reliably on my ancient hardware. Linux eventually worked but it was process. And man pages don’t explain what the system does at all.

JdeBP 9y ago
Of course, as people have pointed out already, a user manual is not a tutorial, and the two are distinct and complementary. This is something that one finds in many spheres, from Microsoft operating systems to Linux ones. One of the things that MSDN and TechNet doco does is have both "X reference" and "using X" sections. Manual pages are reference doco, in this way of organizing things. The BSD worlds put the "using X" doco into what are often called "handbooks" or "guides". * NetBSD Guide: https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html https://freebsd.org/doc/handbook/book.html * DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/ https://www.dragonflybsd.org/docs/handbook/ * TrueOS User Guide: https://www.trueos.org/handbook/trueos.html https://www.trueos.org/handbook/trueos.html * PC-BSD User Guide: http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/) Some parts of the Linux world do the same. upstart had the Upstart Cookbook for example: * http://upstart.ubuntu.com/cookbook/ http://upstart.ubuntu.com/cookbook/ My nosh toolset comes with user manual pages for the individual commands, written in DocBook XML as I just mentioned in https://news.ycombinator.com/item?id=15779321 https://news.ycombinator.com/item?id=15779321 , and a nosh Guide. * http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html * http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-socket.html http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-soc... * http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatsheet.html http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatshe... * http://jdebp.eu./Softwares/nosh/guide.html http://jdebp.eu./Softwares/nosh/guide.html The Linux Documentation Project was supposed to contain a wealth of this stuff, but large parts of it are seemingly moribund, and incomplete after decades or woefully outdated. Wikibooks tried to take up the slack with an "anyone can edit" Guide to Unix and a Linux Guide: * https://en.wikibooks.org/wiki/Guide_to_Unix https://en.wikibooks.org/wiki/Guide_to_Unix * https://en.wikibooks.org/wiki/Linux_Guide https://en.wikibooks.org/wiki/Linux_Guide For examples and doco that works from the basis of what one usually wants to do, then these handbooks and guides are the places to go, not reference manuals.

JdeBP 9y ago

Of course, as people have pointed out already, a user manual is not a tutorial, and the two are distinct and complementary. This is something that one finds in many spheres, from Microsoft operating systems to Linux ones. One of the things that MSDN and TechNet doco does is have both "X reference" and "using X" sections. Manual pages are reference doco, in this way of organizing things. The BSD worlds put the "using X" doco into what are often called "handbooks" or "guides". * NetBSD Guide: https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html https://freebsd.org/doc/handbook/book.html * DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/ https://www.dragonflybsd.org/docs/handbook/ * TrueOS User Guide: https://www.trueos.org/handbook/trueos.html https://www.trueos.org/handbook/trueos.html * PC-BSD User Guide: http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/) Some parts of the Linux world do the same. upstart had the Upstart Cookbook for example: * http://upstart.ubuntu.com/cookbook/ http://upstart.ubuntu.com/cookbook/ My nosh toolset comes with user manual pages for the individual commands, written in DocBook XML as I just mentioned in https://news.ycombinator.com/item?id=15779321 https://news.ycombinator.com/item?id=15779321 , and a nosh Guide. * http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html * http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-socket.html http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-soc... * http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatsheet.html http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatshe... * http://jdebp.eu./Softwares/nosh/guide.html http://jdebp.eu./Softwares/nosh/guide.html The Linux Documentation Project was supposed to contain a wealth of this stuff, but large parts of it are seemingly moribund, and incomplete after decades or woefully outdated. Wikibooks tried to take up the slack with an "anyone can edit" Guide to Unix and a Linux Guide: * https://en.wikibooks.org/wiki/Guide_to_Unix https://en.wikibooks.org/wiki/Guide_to_Unix * https://en.wikibooks.org/wiki/Linux_Guide https://en.wikibooks.org/wiki/Linux_Guide For examples and doco that works from the basis of what one usually wants to do, then these handbooks and guides are the places to go, not reference manuals.