Re: Reference manual + tutorials

[Ricardo Wurmus <rekado@elephly.net>]

Ludovic Courtès <ludo@gnu.org> writes:

> Hello!
>
> Ricardo Wurmus <rekado@elephly.net> 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