[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Reference manual + tutorials
From: |
Ricardo Wurmus |
Subject: |
Re: Reference manual + tutorials |
Date: |
Tue, 29 May 2018 23:53:59 +0200 |
User-agent: |
mu4e 1.0; emacs 25.3.1 |
Ludovic Courtès <address@hidden> writes:
> Hello!
>
> Ricardo Wurmus <address@hidden> skribis:
>
>> It would be great to have both! I’d 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’s not all-or-nothing though. Our manual could be better
> structured and it could include more examples.
>
> I like the “traditional” GNU manuals (libc, Emacs, Gnus, etc.), which
> work very well for me, even though they’re only “locally
> user-story-based”, so to speak.
Yes, this can work. It’s hard for me to imagine where one would put
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’s 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’t separated by step for step instructions.
It would be sad to miss out on good tutorials just because they don’t
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’s difficult to strike the right balance.
--
Ricardo
- Re: Customize GuixSD: Use Stock SSH Agent Everywhere!, (continued)
- Re: Customize GuixSD: Use Stock SSH Agent Everywhere!, Catonano, 2018/05/29
- Re: Customize GuixSD: Use Stock SSH Agent Everywhere!, Ricardo Wurmus, 2018/05/29
- Re: Customize GuixSD: Use Stock SSH Agent Everywhere!, Catonano, 2018/05/29
- Reference manual + tutorials (was: Customize GuixSD: Use Stock SSH Agent Everywhere!), Ricardo Wurmus, 2018/05/29
- Re: Reference manual + tutorials (was: Customize GuixSD: Use Stock SSH Agent Everywhere!), Catonano, 2018/05/29
- Re: Reference manual + tutorials, Julien Lepiller, 2018/05/29
- Re: Reference manual + tutorials, Ricardo Wurmus, 2018/05/29
- Re: Reference manual + tutorials, Ludovic Courtès, 2018/05/29
- Re: Reference manual + tutorials,
Ricardo Wurmus <=
Re: Customize GuixSD: Use Stock SSH Agent Everywhere!, Divan Santana, 2018/05/28