feat: documentation

1 files changed, 78 insertions, 0 deletions

diff --git a/content/blog/2024/good-documentation.md b/content/blog/2024/good-documentation.md
new file mode 100644
index 0000000..095a53d
--- /dev/null
+++ b/content/blog/2024/good-documentation.md
@@ -0,0 +1,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))