rendaw <7e9wc56emjakcm@s.rendaw.me> writes:

> I've written up something similar here:
> https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md

Nice!  Thank you for sharing it.

> I think it would be great to have this information in the
> documentation!

I agree, but I am not sure how to merge the important parts with the
documentation in a way that does not clutter it up and make it even more
confusing than it already is.

> I'd also elaborate on what actually happens in the end
> ("If every service just extends other services, what does the root
> service do?"), how stuff actually runs (since operating systems are
> processes and not data after all -> I think the answer is that the boot
> service, activation service, and shepherd service all run processes but
> that leads to a lot of other obvious questions: what's the difference
> between the boot and activation services - or what do each do and what
> makes them suitable for those tasks, what order are processes started in
> each of them, how does guix deal with existing files created by
> activation processes when reconfiguring the system, etc), what is a
> service vs a service type, and an explanation of the folding process and
> how it relates to a service type definition.

Yes, explaining this could make for a good manual section or blog post.

>> The manual section is helpful
>
> I strongly believe the manual section is not helpful to anyone who
> doesn't already know how Guix works.

It's true that we could do a better job of introducing services in the
manual.

> Reading the source code is a colossal hurdle for users

I think this statement is perhaps over-broad, since "reading the source"
can mean "reading an operating system configuration file," which is
definitely easier than understanding Guix's services.  That said, I
agree that users shouldn't have to grok fold-services just to understand
how to use services in their operating system configuration.  The manual
tries to explain services, but it just doesn't get the job done, and we
should improve it.

> I hope this doesn't come off too aggressive.

I don't think it does, and I appreciate hearing your opinion.  I
actually felt exactly the same way as you, when I was first learning
about services.  It was frustrating.  As I learned, I submitted patches
to change the documentation where it was unclear or incorrect.  But it
still isn't good enough.  I've been thinking about trying to rewrite
that section in a way that makes it easier to understand services for a
first-time reader, but I haven't yet done it.

If you have ideas about how to improve the documentation, please
consider submitting a patch.  Coding can be hard, but so can
documentation.  Every little improvement can help!

-- 
Chris