Hacker News Reader

Comment by native_samples | Hacker News Reader

If anything the biggest problem the systemd docs have is verbosity. It's all classic UNIX man pages, a billion pages of detail on every possible setting with no useful examples anywhere. Fortunately the core system is simple enough that the learning curve isn't too steep but I'd really hate to try and learn it from the official docs. They don't even apply CSS to the HTML versions of the docs.

View on HN

Wikipedia: https://en.wikipedia.org/wiki/Systemd

Web: https://systemd.io/

Src: https://github.com/systemd/systemd

Systemd manpage index: https://www.freedesktop.org/software/systemd/man/

https://www.freedesktop.org/software/systemd/man/systemd.htm... :

  man 1 systemd
  man systemd
  man init

...:

  man systemctl
  man journalctl
  
  man systemd.timer
  man systemd-resolved

The Arch Linux wiki docs for systemd are succinct: https://wiki.archlinux.org/title/systemd

Fedora docs > "Understanding and administering systemd" https://docs.fedoraproject.org/en-US/quick-docs/understandin...

RHEL7 System Administrator’s Guide > "Chapter 10. Managing Services with SystemD" https://access.redhat.com/documentation/en-us/red_hat_enterp...

Well, we also have a very nice manpage viewer.

I think systemd.directives(7) is an often overlooked manpage.

https://man.archlinux.org/man/systemd.directives.7

FWIW, the man.vim vim plugin does grep and some syntax highlighting. https://github.com/vim-utils/vim-man

TIL about that manpage. I've always been guessing at which level in the hierarchy would contain a particular option ("Is it service-specific? Or maybe applies to all execs? Or maybe applies to all units?") and just giving up and opening them all in parallel.

Couldn't agree more. Once familiar with the big picture this page is the best starting point whenever to you want change something.

To get the big picture I read the systemd posts on https://0pointer.net/blog/archives.html But that's 10 years already! No idea what would be recommended today.

Yes, the Arch docs are the best. But they aren't from the systemd project itself, are they?

And, as a Debian user who often finds himself on the Arch docs - there's a ton of distro-specific stuff in the Arch wiki. And rightfully so - it's a wiki for a distro.

These sorta landmines when trying to just research/digest a concept can really suck. OP's tool really eloquently breaks things down to _just_ core concepts so you can quickly start to grok what I consider to be a relatively complex tool.

In my experience very little of it is distro-specific, especially if you're on a distro that has similar components as Arch. I'm on OpenSUSE Tumbleweed, which also uses systemd, etc and is a rolling distro with the latest versions of everything, so a lot of the wiki articles apply directly as long as I translate the package names.

Agree - but there's still bits and pieces that don't translate over to other distros which can suck if you're jumping into to learning something. When I read the Arch Wiki as a Debian user I realize I'm reading it through the lens of someone using a different distro.

Overall I use the Arch wiki very often and it's because of the exact point you're making - I'm just being pedantic saying those slight distro differences can be a pain.

This isn't a knock but it's exactly what I was talking about and why I find OP's learning tool to be so valuable.

Lots of folks learn by example and hands-on labs. Personally, I'd much rather learn the basic ropes by jumping into a tool like OP's vs. finding/digging through all of these resources. I'll also criticize to say you likely already know much about systemd, and were able to pull/filter these resources much easier vs someone completely new to the concepts.

To illustrate further: vim is another tool that has outstanding learning resources, everything from very quick "hey get started" examples docs all the way up to adventure games. If I had to go back and relearn vim I would absolutely do it this way vs. digging on man pages like when I was a kid in the 90's. Personally, I learn by doing.

---

Overall - OP's thingy is what I would call a "rich interactive learning tool." It's anecdotal, and obvious projection - but _for me_, interactive learning tools optimize the time it takes to fully "grok" a subject from scratch vs. jumping into a bunch of docs/man pages.

I often find the `## Usage Examples` heading in manages to be most helpful, too.

~Examples as Integration Tests as executable notebooks with output and state assertions may incur less technical debt.

How to manage containers with [MicroShift] k8s/k3d with systemd might be a good example.

Read the Source, Read the Docs, Write the Docs, post the Link to the actual Source of the docs: https://github.com/systemd/systemd/blob/main/docs/index.md

Systemd man pages source: https://github.com/systemd/systemd/tree/main/man

Also https://www.freedesktop.org/software/systemd/man/systemd.mou... https://github.com/systemd/systemd/blob/main/man/systemd-mou... :

  man systemd.mount

And almost none of the tools help you naturally discover the missing feature you didn't know to solve the problem in the most "systemd*" way.

The docs are not friendly enough to introduce you to new tools, and they're mostly shallow enough to not explain the technical details of how things interact or where all the defaults are stored. They exist but clearly this page exists because they need to improve.

I know, I know, pull requests welcome....

At that point I'd call the docs a developer guide rather than the docs a sleep deprived sysadmin needs at 3am to fix a server

Reply on news.ycombinator.com