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