Ricardo:
Thats very good advice and will be a useful guide in refactoring the parts of the system services documentation. I think in general, we need to find a nice middle ground between the extremely general and the immediately sensible, as I remember when I first got into guix 1.5 years ago, arriving at services left me very confused. While as a recent PhD candidate in philosophy of mathematics I'm a fellow appreciator of the power of generality (the extreme genericity of scheme and guix is why I'm here!), I also think if it doesn't obey strict linguistic rules it can antithetical to its original purpose. For example, I remember being very confused about "file-like objects", for the simple reason that it wasn't "a file or file-like object". While this might come from a GNU terminological lineage i'm unaware of, my immediate reaction to trying to understand file-likeness is the simple rule that a semblance is strictly not what it resembles, and likeness qualifies semblance. It would be improper to place phones in a category of "phone-like objects", because the likeness assumes a distinction from the thing itself. Perhaps it could be justified if we dive into the minutiae of paraconsistent logic, but I think then we are going to far (also, isn't 'everything a file' a motto of Unix, even if gnu is strictly not?). But I've digressed; I think your straightforward description above communicates many of the ideas better than the docs, but I think this is a situation where we can have our cake and eat it too, so to speak; usually, an appendage such as "file AND file-like objects" will accomplish much of the work for us.
Catonano:
I think writing a home-service is much easier given that you don't need to do produce an entire system generation before you find out what you did wrong; it just depends on if you need your service initialized at startup (system-services, globally defined and available prior to login) rather than at login (home-services, per-user/locally defined).
I'm not on Mastodon but feel free to send your service my way for some help, I'm still a beginner but a second pair of eyes is always nice to have.
ez,
b