Hi Thomas, "Thomas Ieong" <th.ie...@free.fr> writes:
> Hey Guix, > > I was thinking about how we could do better documentation wise and came up > with some ideas. > > - Let people comment via a web interface on issues.guix.gnu.org I think it > would help a lot and lower the barrier to entry. I know we're supposed > to move to codeberg but it would not hurt enabling it in the meantime > > Anyone knows why it is/has been disabled? It's been buggy in the past, and it would silently swallow people's reply, which is much worst than not permitting it in the first place. Fixes welcome; it should have system tests ideally since it's critical that it truly works. > It would be nice to have user notes below the manuals too just like it's > done > in the PHP world to let people know what's the actual state of the things > we're documenting. > > One example where this would have been useful to me is docker, what we have > packaged in Guix is severely > outdated, and when I was at the meeting held by Tanguy he just told me that > everyone using podman anyways, I think you should not have to search through > mail/irc/attend event to know that. I think we could add footnote for that. But really, what would be ideal is someone steps up to update the docker package in Guix, instead of documenting that 'beware, our package is currently outdated'. > - Add a banner to tell you if you're consulting the manual for Guix devel or > fixed version like 1.4.0 > > Sometimes I forget and I think I'm not the only one, that I'm viewing the > Guix manual for 1.4.0 while I was really looking for things that are in the > devel manual. > > I looked briefly at the code and you'd have to dig into the docs/build.scm > file to add the relevant code. That's been brought up by Tobias in the past. They suggested showing the dev version by default. And we could have some selector somewhere to show past versions. > - Add an awesome list > > I don't know about you, but when I got started with Guix I would often end > up in a situation where the manuals/cookbook were incomplete or not clear > about how > to set up service/package X,Y,Z or config.scm > > I would do a web search, find some random dotfiles that would fit my need > and just copy paste that and when the web search didn't yield anything > I'd stalk active member of this list or on IRC that seems to know > what they were doing to lift parts of their dotfiles. > > That awesome list could also include services like this one: > > https://toys.whereis.social/ > > which tells you if a package you need exists on some other channels. Not a bad idea, my only fear is that it could go out of date quickly. > - Make more videos about GNU/Guix on Peertube for example > > On the top off my head I only know about Andrew Tropin and David Wilson > making youtube video about Guile and GNU Guix. > > We could have a peertube channel with monthly/weekly live on various topics > > I do not know if we could just reuse some peertube instances or host our > own. > > I would be up to post some, on how to have a reliable mail server with Guix, > having an actual example of the workflow you should have when contributing > to > this mailing list etc That's always welcome! If you have the drive, go for it! > - Add a Guix extension named scaffold to quickly have a package skeleton > > Sometimes I'm hacking on some python packages or golang packages that I > created, I try to package it for guix, but I never know which use-module > I should use, at the event held by Tanguy people told me they just know > from reading the source code, copy pasting. > > So I thought about a small helper that would give me the right modules that > I need. It could be cool if the importer could be told in which module the new package should be added, and take care of adjusting the imports automatically. -- Thanks, Maxim
