Reference manual + tutorials (was: Customize GuixSD: Use Stock SSH Agent Everywhere!)

[Ricardo Wurmus]

Hi Catonano,

>> > In this regard, I'd lie to suggest this talk, I think it's relevant
>> > https://archive.fosdem.org/2017/schedule/event/legacy_docs/
>> >
>> > It'd be very useful for Guile too and God knows for how many more GNU
>> > projects
>>
>> Could you please summarize the key points and how they apply to this
>> discussion?
>>
>
>
> Sure ! Thanks for asking ! 😃
>
> I think a good starting point is this picture
> https://files.mastodon.social/media_attachments/files/003/855/604/original/b02a794729c184ad.png

[…]

Thank you for the summary!

I think that both styles are important.  A reference manual is great
when looking up information and to figure out uncommon workflows.  It’s
also good to have a single section that describes all features of a
tool, which otherwise would have to be extracted from user stories.

Having a document that is centered around user stories is also very
useful, as they make it easier for readers to see their own needs in
them and find the appropriate recipe that leads them to a solution more
quickly.

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.

How to begin, though…? :)

--
Ricardo