1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
+++
title = "Things I care about: documentation"
author = ["Michał Sapka"]
date = 2024-12-04T22:08:00+01:00
categories = ["blog"]
draft = false
weight = 2001
image_dir = "blog/images"
image_max_width = 600
Abstract = "The stuff dreams are made of"
+++
This is a new passion for me.
For _ages_ I was googling-first, and only then looking into documentation.
And it was one of the worst mistakes I've ever made.
It's the standard way to start things, but it makes it impossible to be good at them.
I know how this changed: I moved to FreeBSD.
Say what you will about Linux/Mac/and so on - their documentation is terrible.
BSDs however threat their docs with love and care they deserve.
There is, however, another reason.
And thisone makes me sad.
So many of my colleagues limit themselves to asking ChatGPT "how to I reverse a string".
That's no way to learn, to grow.
The only thing you are achieving by that is making themselves more reliant on some new gadget and the destruction the planet.
There should a world for people like me, who judge others based on their use of GenAI.
Something positive, of course.
But back to documentation.
I participate in Advent of Code, which requires me to find APIs I may have used 10 years ago.
But all I really need is to know if I'm thinking about string, enumerable, or integer.
Everything else is simply there, waitin, happy to share it's knowledge.
It's available for free and written in languge I understand.
At this point, the first place I go to when encountering a problem are man-pages, then online docs.
Stack Overflow, Reddit, and so on are simply terrible.
Outdated, full of hate, done for some internet points.
Having your documentation be Github or Discord is a slap in the face - I can't search or _even access_ it without giving my data to a malicious agent.
I now understand why _gurus_[^fn:1] in their 50s, 60s and so on are so good at whey did.
They had to look up documentation, so they had to know what they were looking for.
And in the process they most likely learned a lot of random things.
They didn't waste their time with "Learn SQL in 20 minutes. Complete Course from begginer to expert" on YouTube by "TechChan2000".
I've mentioned that I use Vim(1) quite a lot now.
And while yes, sometimes I hit a wall and ask on IRC, most of my problems can be simply solved by a quick `:h`.
There is nothing better than having documentation distributed with programs or operating systems.
Good documentation is the goal, but _having it_ is the first step.
A lot of modern software doesn't come with manual.
Some of it even doesn't have online documentation.
And while I get that one may sometimes need to pay for it (is it still the case?), it needs to exist.
At this point I want my docs to:
1. Be easily accessible, preferably from shell. Browser depletes my small reserves of focus.
2. Have general introduction (think `man man`). I want to know what we are talking about.
3. Have details. Yeah, this is most likely what I am looking for.
4. Have EXAMPLES. BSDs have this perfected.
Pretty soon I will refuse to use software without proper documentation.
And I find this as a surprise, as it wasn't the case, but having _good_ documentation at hand is additive.
Not having to rely on mediocre search engine is the stuff dreams are made of.
----
`Man pages` have a bad rap, as they tend to be long and difficult to comprehend.
But if one dedicates enough time to learn how to use them, it will pay significant dividends.
People also tend to have a hard time finding things in there.
Luckily there is `apropos(1)` and `whatis(1)`, which, in tandem, let us search for manpages related to what we are looking for.
Of couse, we can `man apropos` and `man man`.
[^fn:1]: n. [UNIX] An expert. Implies not only wizard skill but
also a history of being a knowledge resource for others. Less
often, used (with a qualifier) for other experts on other systems,
as in \`VMS guru' (via [The Hacker's Dictionary](https://latel.upf.edu/morgana/altres/cibres/hackers/Hacker_G.html#entr_089))
|
