Merge branch 'master' into staging

1 files changed, 48 insertions, 6 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index e1902f120f..6a2564b07d 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -29,6 +29,7 @@ choice.
 * Tracking Bugs and Patches::   Keeping it all organized.
 * Commit Access::               Pushing to the official repository.
 * Updating the Guix Package::   Updating the Guix package definition.
+* Writing Documentation::       Improving documentation in GNU Guix.
 * Translating Guix::            Make Guix speak your native language.
 @end menu
 
@@ -664,7 +665,7 @@ hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}).  However you
 should be careful when using some characters for example @samp{@@} and
 curly braces which are the basic special characters in Texinfo
 (@pxref{Special Characters,,, texinfo, GNU Texinfo}).  User interfaces
-such as @command{guix package --show} take care of rendering it
+such as @command{guix show} take care of rendering it
 appropriately.
 
 Synopses and descriptions are translated by volunteers
@@ -1118,11 +1119,11 @@ Development is done using the Git distributed version control system.
 Thus, access to the repository is not strictly necessary.  We welcome
 contributions in the form of patches as produced by @code{git
 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list
-(@pxref{submitting patches,, Submitting patches to a project, git, Git
-User Manual}).  Contributors are encouraged to take a moment to set some
-Git repository options (@pxref{Configuring Git}) first, which can
-improve the readability of patches.  Seasoned Guix developers may also
-want to look at the section on commit access (@pxref{Commit Access}).
+(@pxref{Submitting patches to a project,,, git, Git User Manual}).
+Contributors are encouraged to take a moment to set some Git repository
+options (@pxref{Configuring Git}) first, which can improve the
+readability of patches.  Seasoned Guix developers may also want to look
+at the section on commit access (@pxref{Commit Access}).
 
 This mailing list is backed by a Debbugs instance, which allows us to
 keep track of submissions (@pxref{Tracking Bugs and Patches}).  Each
@@ -1779,6 +1780,47 @@ This check can be disabled, @emph{at your own peril}, by setting the
 this variable is set, the updated package source is also added to the
 store.  This is used as part of the release process of Guix.
 
+@cindex documentation
+@node Writing Documentation
+@section Writing Documentation
+
+Guix is documented using the Texinfo system.  If you are not yet
+familiar with it, we accept contributions for documentation in most
+formats.  That includes plain text, Markdown, Org, etc.
+
+Documentation contributions can be sent to
+@email{guix-patches@@gnu.org}.  Prepend @samp{[DOCUMENTATION]} to the
+subject.
+
+When you need to make more than a simple addition to the documentation,
+we prefer that you send a proper patch as opposed to sending an email
+as described above.  @xref{Submitting Patches} for more information on
+how to send your patches.
+
+To modify the documentation, you need to edit @file{doc/guix.texi} and
+@file{doc/contributing.texi} (which contains this documentation
+section), or @file{doc/guix-cookbook.texi} for the cookbook.  If
+you compiled the Guix repository before, you will have
+many more @file{.texi} files that are translations of these
+documents.  Do not modify them, the translation is managed through
+@uref{https://translate.fedoraproject.org/projects/guix, Weblate}.
+@xref{Translating Guix} for more information.
+
+To render documentation, you must first make sure that you ran
+@command{./configure} in your source tree (@pxref{Running Guix Before
+It Is Installed}).  After that you can run one of the following
+commands:
+
+@itemize
+@item @samp{make doc/guix.info} to compile the Info manual.
+      You can check it with @command{info doc/guix.info}.
+@item @samp{make doc/guix.html} to compile the HTML version.
+      You can point your browser to the relevant file in the
+      @file{doc/guix.html} directory.
+@item @samp{make doc/guix-cookbook.info} for the cookbook Info manual.
+@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
+@end itemize
+
 @cindex translation
 @cindex l10n
 @cindex i18n