2018-05-29 15:42 GMT+02:00 Ricardo Wurmus <rekado@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