Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.



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/

* FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html

* DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/

* TrueOS User Guide: https://www.trueos.org/handbook/trueos.html

* PC-BSD User Guide: 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/

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 , and a nosh Guide.

* http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html

* http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-soc...

* http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatshe...

* 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/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.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: