unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed

From: ludo@gnu.org (Ludovic Courtès)
To: myglc2 <myglc2@gmail.com>
Cc: guix-devel@gnu.org
Subject: Re: [PATCH] Quick-start guide
Date: Sun, 12 Jun 2016 22:46:10 +0200	[thread overview]
Message-ID: <87twgyi19p.fsf@gnu.org> (raw)
In-Reply-To: <86r3c2a17p.fsf@gmail.com> (myglc2@gmail.com's message of "Sun, 12 Jun 2016 11:14:34 -0400")

Hi!

myglc2 <myglc2@gmail.com> skribis:

> This is the correct goal, but the manual as it stands is problematic for
> first-time users for reasons such as: it's overwhelmingly copious;
> information is "shredded" into different sections; the is confusing
> terminology; finding one's way around is difficult; there is virtually
> no guidance of what to read first or how to proceed.

Woow, that’s a lot of room for progress.  :-)

I think all of these issues need to be clarified and addressed.

The problem for me as a maintainer is that we don’t have a test suite
for the manual.  So I cannot simply apply a big patch and run “make
check” to ensure that nothing “broke” in the manual.  So I’m both
receptive and demanding here ;-), because it’s often the case that
editing the manual is more work than adding a couple of paragraphs here
and there.

> I see this patch as an attempt to address some of these difficulties.

Sure, my concern is about the duplication of information and additional
maintenance burden that ensues.

> I suggest we add a new "Getting Started" section between "Introduction"
> and "Installation". "Getting Started" should initially include a
> discussion of how to decide whether to install Guix or GuixSD and
> quick-start sections for each.

That sounds like a good idea.  To begin with, would you like to propose
a “Guix Quick Start” section that we could put between the “Features”
and “Invoking ‘guix package’” sections?

Thanks,
Ludo’.

next prev parent reply	other threads:[~2016-06-12 20:46 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-06-04 20:00 [PATCH] Quick-start guide yoosty
2016-06-08 12:47 ` Ludovic Courtès
2016-06-11 13:43   ` yoosty
2016-06-11 17:49     ` Leo Famulari
2016-06-12 15:14       ` myglc2
2016-06-12 20:46         ` Ludovic Courtès [this message]
2016-06-15  5:07       ` yoosty
2016-06-16 10:51         ` Ludovic Courtès
2016-06-24  4:55           ` yoosty
2016-06-24 12:36             ` Ludovic Courtès
2016-06-13  0:40 ` John Darrington

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://guix.gnu.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87twgyi19p.fsf@gnu.org \
    --to=ludo@gnu.org \
    --cc=guix-devel@gnu.org \
    --cc=myglc2@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).