From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ricardo Wurmus Subject: Re: Reference manual + tutorials Date: Tue, 29 May 2018 23:53:59 +0200 Message-ID: <877enmqgaw.fsf@elephly.net> References: <87h8mu1lv9.fsf@gnu.org> <87muwk2fok.fsf@gmail.com> <87h8mshvdz.fsf@elephly.net> <87lgc2r31y.fsf@elephly.net> <87h8mqqzle.fsf@elephly.net> <87muwiuu9u.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:40467) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fNmZU-0005oR-KZ for guix-devel@gnu.org; Tue, 29 May 2018 17:54:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fNmZS-0000SO-G5 for guix-devel@gnu.org; Tue, 29 May 2018 17:54:24 -0400 Received: from sender-of-o51.zoho.com ([135.84.80.216]:21103) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fNmZS-0000Ri-6l for guix-devel@gnu.org; Tue, 29 May 2018 17:54:22 -0400 In-reply-to: <87muwiuu9u.fsf@gnu.org> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Ludovic =?utf-8?Q?Court=C3=A8s?= Cc: Guix-devel Ludovic Court=C3=A8s writes: > Hello! > > Ricardo Wurmus skribis: > >> It would be great to have both! I=E2=80=99d like the existing reference= manual >> to remain as the canonical description of all features of Guix, so that >> an additional story-centered document (whether that be a dedicated >> section or a separate file) can guide readers to more information if >> they might need it. > > I think it=E2=80=99s not all-or-nothing though. Our manual could be bett= er > structured and it could include more examples. > > I like the =E2=80=9Ctraditional=E2=80=9D GNU manuals (libc, Emacs, Gnus, = etc.), which > work very well for me, even though they=E2=80=99re only =E2=80=9Clocally > user-story-based=E2=80=9D, so to speak. Yes, this can work. It=E2=80=99s hard for me to imagine where one would pu= t prose that resembles a tutorial in our current manual. It currently leans very heavily towards a reference manual, which discourages me from adding elaborate examples. There=E2=80=99s also the danger of interrupting the flow with too many big inline examples. Currently, it is easy to understand the big picture because the prose isn=E2=80=99t separated by step for step instructions. It would be sad to miss out on good tutorials just because they don=E2=80= =99t fit into the current manual; and it would be just as sad to clutter the manual by filling it with tutorials that would seem out of place. It=E2=80=99s difficult to strike the right balance. -- Ricardo