doc: Turn "Creating a Channel" into a step-by-step guide.

* doc/guix.texi (Creating a Channel): Rewrite as a step-by-step guide.
Move warning below and shorten it.

doc/guix.texi

@@ -5771,18 +5771,99 @@ machines with limited resources.
 Let's say you have a bunch of custom package variants or personal packages
 that you think would make little sense to contribute to the Guix project, but
 would like to have these packages transparently available to you at the
-command line.  You would first write modules containing those package
+command line.  By creating a @dfn{channel}, you can use and publish such
-definitions (@pxref{Package Modules}), maintain them in a Git repository, and
+a package collection.  This involves the following steps:
-then you and anyone else can use it as an additional channel to get packages
+
-from.  Neat, no?
+@enumerate
+@item
+Channels live in a Git repository so the first step, when creating a
+channel, is to create its repository:
+
+@example
+mkdir my-channel
+cd my-channel
+git init
+@end example
+
+@item
+The next step is to create files containing package modules
+(@pxref{Package Modules}), each of which will contain one or more
+package definitions (@pxref{Defining Packages}).  A channel can provide
+things other than packages, such as build systems or services; we're
+using packages as most common use case.
+
+For example, Alice might want to provide a module called @code{(alice
+packages greetings)} that will provide her favorite ``hello world''
+implementations.  To do that Alice will create a directory corresponding
+to that module name.
+
+@example
+mkdir -p alice/packages
+$EDITOR alice/packages/greetings.scm
+git add alice/packages/greetings.scm
+@end example
+
+You can name your package modules however you like; the main constraint
+to keep in mind is to avoid name clashes with other package collections,
+which is why our hypothetical Alice wisely chose the @code{(alice
+packages @dots{})} name space.
+
+Note that you can also place modules in a sub-directory of the
+repository; @pxref{Package Modules in a Sub-directory}, for more info on
+that.
+
+@item
+With this first module in place, the next step is to test the packages
+it provides.  This can be done with @command{guix build}, which needs to
+be fold to look for modules in the Git checkout.  For example, assuming
+@code{(alice packages greetings)} provides a package called
+@code{hi-from-alice}, Alice will run this command from the Git checkout:
+
+@example
+guix build -L. hi-from-alice
+@end example
+
+@noindent
+... where @code{-L.} adds the current directory to Guile's load path
+(@pxref{Load Paths,,, guile, GNU Guile Reference Manual}).
+
+@item
+It might take Alice a few iterations to obtain satisfying package
+definitions.  Eventually Alice will commit this file:
+
+@example
+git commit
+@end example
+
+As a channel author, consider bundling authentication material with your
+channel so that users can authenticate it.  @xref{Channel
+Authentication}, and @ref{Specifying Channel Authorizations}, for info
+on how to do it.
+
+@item
+To use Alice's channel, anyone can now add it to their channel file
+(@pxref{Specifying Additional Channels}) and run @command{guix pull}
+(@pxref{Invoking guix pull}):
+
+@example
+$EDITOR ~/.config/guix/channels.scm
+guix pull
+@end example
+
+Guix will now behave as if the root directory of that channel's Git
+repository had been permanently added to the Guile load path.  In this
+example, @code{(alice packages greetings)} will automatically be found
+by the @command{guix} command.
+@end enumerate
+
+Voilà!  
 
 @c What follows stems from discussions at
 @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
 @c earlier discussions on guix-devel@gnu.org.
 @quotation Warning
-Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
+Before you publish your channel, we would like to share a few words of
-publish your personal channel to the world, we would like to share a few words
+caution:
-of caution:
 
 @itemize
 @item
@@ -5793,13 +5874,11 @@ available to all Guix users and benefit from the project's quality assurance
 process.
 
 @item
-When you maintain package definitions outside Guix, we, Guix developers,
+Package modules and package definitions are Scheme code that uses
-consider that @emph{the compatibility burden is on you}.  Remember that
+various programming interfaces (APIs).  We, Guix developers, never
-package modules and package definitions are just Scheme code that uses various
+change APIs gratuitously, but we do @emph{not} commit to freezing APIs
-programming interfaces (APIs).  We want to remain free to change these APIs to
+either.  When you maintain package definitions outside Guix, we consider
-keep improving Guix, possibly in ways that break your channel.  We never
+that @emph{the compatibility burden is on you}.
-change APIs gratuitously, but we will @emph{not} commit to freezing APIs
-either.
 
 @item
 Corollary: if you're using an external channel and that channel breaks, please
@@ -5813,21 +5892,6 @@ share your improvements, which are basic tenets of
 email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
 @end quotation
 
-To create a channel, create a Git repository containing your own package
-modules and make it available.  The repository can contain anything, but a
-useful channel will contain Guile modules that export packages.  Once you
-start using a channel, Guix will behave as if the root directory of that
-channel's Git repository has been added to the Guile load path (@pxref{Load
-Paths,,, guile, GNU Guile Reference Manual}).  For example, if your channel
-contains a file at @file{my-packages/my-tools.scm} that defines a Guile
-module, then the module will be available under the name @code{(my-packages
-my-tools)}, and you will be able to use it like any other module
-(@pxref{Modules,,, guile, GNU Guile Reference Manual}).
-
-As a channel author, consider bundling authentication material with your
-channel so that users can authenticate it.  @xref{Channel
-Authentication}, and @ref{Specifying Channel Authorizations}, for info
-on how to do it.
 
 
 @node Package Modules in a Sub-directory