"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 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. > > - 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. > > - 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. > > - 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 > > - 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. > > > I Cced you Maxim because I think I saw your name in the documentation team. > > Thoughts?
Totally agree! Those are all good points, I would add that it would be nice to show what modules each documentation page talks about. I’m thinking in the style of info (libc) or the man-pages that always show the corresponding headers at the top of the page. Well of course, it just takes someone to do it :P Have a nice day, Noé
signature.asc
Description: PGP signature
