2018-05-29 15:42 GMT+02:00 Ricardo Wurmus <rek...@elephly.net>: > > 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 The key point of the talk is that the documentation usually illustrates the technical features of a project And the process of envisioning solutions for use cases is left to the reader Instead, the documentation should start from specific use cases. It should be an anthology of use cases As for Guile, for example, Thomas Dankaert recently posted a question on the guile user mailing list about how to use string as ports in calling external commands; he wanted the error port of an external command to be a string The manual deals with input output in several locations scattered all around Drawing a working solution for reading/writing is not exactly immediate A bunch of examples would be more funcional, at least for some kinds of readers/users And input output is only one kind of use cases Regarding Guix, having examples of use cases of using packages could be a good starting point So, finally, I think your idea of having a separate document providing a different angle to using Guix is a good one Other categories of use cases could be envisioned It could cover not only the usage of specific packages but also some GuixSD functionalities such as updating, setting up specific desktop environments, services, reconfiguring Those things are quite different from the common usage patterns of mainstream distros and some reading-phobic people could use some quick general examples to draw a general picture of Guix on their own Maybe the traditional manual could be a further resource for those who want to deepen their knowledge of Guix How much am I ready to contribute to such a document ? I don't know I chimed in because I found interesting that a similar idea to that illustrated in the talk came afloat here
