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
