4 ms·

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

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.

westurner 5y ago
Wikipedia: https://en.wikipedia.org/wiki/Systemd https://en.wikipedia.org/wiki/Systemd Web: https://systemd.io/ https://systemd.io/ Src: https://github.com/systemd/systemd https://github.com/systemd/systemd Systemd manpage index: https://www.freedesktop.org/software/systemd/man/ https://www.freedesktop.org/software/systemd/man/ https://www.freedesktop.org/software/systemd/man/systemd.html# 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 https://wiki.archlinux.org/title/systemd Fedora docs > "Understanding and administering systemd" https://docs.fedoraproject.org/en-US/quick-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_enterprise_linux/7/html/system_administrators_guide/chap-managing_services_with_systemd https://access.redhat.com/documentation/en-us/red_hat_enterp...
- Foxboron 5y ago
  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 https://man.archlinux.org/man/systemd.directives.7
  - westurner 5y ago
    FWIW, the man.vim vim plugin does grep and some syntax highlighting. https://github.com/vim-utils/vim-man https://github.com/vim-utils/vim-man
  - Arnavion 5y ago
    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.
  - usr1106 5y ago
    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 https://0pointer.net/blog/archives.html But that's 10 years already! No idea what would be recommended today.
- native_samples 5y ago
  Yes, the Arch docs are the best. But they aren't from the systemd project itself, are they?
  - peterangular 5y ago
    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.
    - Arnavion 5y ago
      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.
      - peterangular 5y ago
        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.
- peterangular 5y ago
  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.
  - westurner 5y ago
    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.
    - westurner 5y ago
      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 https://github.com/systemd/systemd/blob/main/docs/index.md Systemd man pages source: https://github.com/systemd/systemd/tree/main/man https://github.com/systemd/systemd/tree/main/man Also https://www.freedesktop.org/software/systemd/man/systemd.mount.html# https://www.freedesktop.org/software/systemd/man/systemd.mou... https://github.com/systemd/systemd/blob/main/man/systemd-mount.xml https://github.com/systemd/systemd/blob/main/man/systemd-mou... : man systemd.mount
- rob_c 5y ago
  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....
rob_c 5y ago
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

westurner 5y ago

Wikipedia: https://en.wikipedia.org/wiki/Systemd https://en.wikipedia.org/wiki/Systemd Web: https://systemd.io/ https://systemd.io/ Src: https://github.com/systemd/systemd https://github.com/systemd/systemd Systemd manpage index: https://www.freedesktop.org/software/systemd/man/ https://www.freedesktop.org/software/systemd/man/ https://www.freedesktop.org/software/systemd/man/systemd.html# 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 https://wiki.archlinux.org/title/systemd Fedora docs > "Understanding and administering systemd" https://docs.fedoraproject.org/en-US/quick-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_enterprise_linux/7/html/system_administrators_guide/chap-managing_services_with_systemd https://access.redhat.com/documentation/en-us/red_hat_enterp...

Foxboron 5y ago
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 https://man.archlinux.org/man/systemd.directives.7
- westurner 5y ago
  FWIW, the man.vim vim plugin does grep and some syntax highlighting. https://github.com/vim-utils/vim-man https://github.com/vim-utils/vim-man
- Arnavion 5y ago
  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.
- usr1106 5y ago
  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 https://0pointer.net/blog/archives.html But that's 10 years already! No idea what would be recommended today.
native_samples 5y ago
Yes, the Arch docs are the best. But they aren't from the systemd project itself, are they?
- peterangular 5y ago
  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.
  - Arnavion 5y ago
    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.
    - peterangular 5y ago
      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.
peterangular 5y ago
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.
- westurner 5y ago
  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.
  - westurner 5y ago
    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 https://github.com/systemd/systemd/blob/main/docs/index.md Systemd man pages source: https://github.com/systemd/systemd/tree/main/man https://github.com/systemd/systemd/tree/main/man Also https://www.freedesktop.org/software/systemd/man/systemd.mount.html# https://www.freedesktop.org/software/systemd/man/systemd.mou... https://github.com/systemd/systemd/blob/main/man/systemd-mount.xml https://github.com/systemd/systemd/blob/main/man/systemd-mou... : man systemd.mount
rob_c 5y ago
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....

rob_c 5y ago

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