mbox series

[bug#66577,0/4] Newcomer-oriented improvements to the manual and cookbook

Message ID cover.1697459606.git.ludo@gnu.org
Headers show
Series Newcomer-oriented improvements to the manual and cookbook | expand

Message

Ludovic Courtès Oct. 16, 2023, 12:36 p.m. UTC 
Hello!

These patches reorganize things a bit in the manual to make important
things more easily findable to newcomers, and adds a word of caution
regarding the section on multiple profiles in the cookbook (I’ve seen
newcomers attempt to adopt that software management style on their
systems, when it’s complex and in fact largely unnecessary since the
addition of a fast cache in ‘guix shell’).

Thoughts?

Ludo’.

Ludovic Courtès (4):
  doc: Move “System Troubleshooting Tips” below.
  doc: Mention Guix Home in “Getting Started”.
  doc: cookbook: Suggest ‘guix shell’ as an alternative to multiple
    profiles.
  doc: cookbook: Add cross references to the manual regarding manifests.

 doc/guix-cookbook.texi |  51 ++++----
 doc/guix.texi          | 257 ++++++++++++++++++++---------------------
 2 files changed, 152 insertions(+), 156 deletions(-)


base-commit: a0d2ecde943bd1854ddbb7c0cad35a1fc64dc5ab

Comments

Mathieu Othacehe Oct. 17, 2023, 10:05 a.m. UTC | #1 
Hello,

> regarding the section on multiple profiles in the cookbook (I’ve seen
> newcomers attempt to adopt that software management style on their
> systems, when it’s complex and in fact largely unnecessary since the
> addition of a fast cache in ‘guix shell’).

It is clear that "guix shell" is now an easier alternative to manual
profile management. So that commit:

>
>   doc: cookbook: Suggest ‘guix shell’ as an alternative to multiple
>     profiles.

and the rest of the series looks good to me.

Thanks,

Mathieu
Simon Tournier Oct. 18, 2023, 4:34 p.m. UTC | #2 
Hi,

Cool!  That’s better.

On Mon, 16 Oct 2023 at 14:36, Ludovic Courtès <ludo@gnu.org> wrote:

> Ludovic Courtès (4):
>   doc: Move “System Troubleshooting Tips” below.
>   doc: Mention Guix Home in “Getting Started”.
>   doc: cookbook: Suggest ‘guix shell’ as an alternative to multiple
>     profiles.
>   doc: cookbook: Add cross references to the manual regarding manifests.

LGTM, except keep the mention about profile in “Going further” of
“Getting Started”.

Cheers,
simon
Ludovic Courtès Oct. 24, 2023, 4:12 p.m. UTC | #3 
Hey,

Pushed as 216f8ffff49c54ad56209c4fd6528f2d80ee8fed with the change Simon
suggested.  Thank you Mathieu and Simon for your feedback!

Ludo’.