Re: Feedback of the GNU Guix manual

[Matt]

I care about this.  How can I help?

- Convert the notes into patches?
- Proofread any patches that derive from Christian's efforts?
 
 ---- On Sun, 14 Jan 2024 16:01:58 +0100  Christian Miller  wrote --- 

 > I read through the GNU Guix manual on revision
 > ee7c9d254117fa470686210ad2ef5e7f1ba4fefc with Emacs in TTY mode.

What's TTY mode?  M-x tty <tab> reveals nothing for me.
 
 > As a beginner, the manual was helpful and I learned lot's of stuff.
 > Though it felt heartless.  No consistency and sometimes the structure
 > is confusing (especially the contributing part, since it tries to get
 > GNU Guix System and GNU Guix under one section and it was kinda
 > confusing for me).

Thank you for sharing your experience.  I'm sorry it wasn't more positive.  
I've found it challenging to read as well.

 > It seems that there is no style guide.  Sometimes default values are
 > mentioned and sometimes not.  Also some use uppercase and other use
 > lowercase for type of variable.  There is also Scheme code which is
 > most of the time in the old style notation.  For me as a beginner,
 > this was confusing.

The GNU project has several:

- https://www.gnu.org/prep/standards/html_node/Documentation.html
- https://www.fsf.org/licensing/gnu-press/GNU-Press-styleguide.pdf

 > I will mention lot's of style issues since at that time I did not know
 > it is in such a bad state.

I respectfully disagree that it's in bad taste to mention them.  I find such 
feedback helpful towards correcting the problems you experience.  I appreciate 
you taking the time to write them all up.  It's nice to know someone reads the 
manual! :)

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode