contribute with content in our official help pages?

[Giovanni Biscuolo]

Hi Simon and all readers,

I have some comments I cannot keep, just to try helping making this
thread harder to follow, if possible :-D.

Simon Tournier <zimon.toutoune@gmail.com> writes:

[...]

> For instance, Vim [1] or VSCode [2].  The frame is not “what we should
> do” but “let me show you what I have”, IMHO.  Well, you are free to
> join the fun! :-)
>
[1] https://10years.guix.gnu.org/video/using-vim-for-guix-development/
[2] 
https://videos.univ-grenoble-alpes.fr/video/26660-cafe_guix_vscode_comme_outil_deditionmp4/

Thank you for the pointers, Simon, I already knew [1] since I have a
look to 10years Guix from time to time but I missed [2].  Although I
don't personally use that tools, I find that information useful when
Someone™ asks me how do Something™ using tool XYZ with Guix... but I'm
sure in 5 minutes I'll forget almost all, since I don't usualy use all
XYZ tools.

How can we decrease the effort needed by Someone™ like me to find useful
informations on "how to do X with/in Guix"?

1. The "quick and dirty" solution is to use a "smart" query in a web
search engine:

Example query "guix write packages using vim":
https://duckduckgo.com/?q=guix+write+packages+using+vim

It's not very efficient since the searcher have to do some _hard_ work
first to find a "smart" query and then to filter out what he really
needs; last but not least to understand if that information is still
relevant or someway outdated or not working for his use-case.

I'd call this quite a high cognitive overhead.

2. Search one of our _official_ "Guix - Help" resources:
https://guix.gnu.org/en/help/

As you can see, We™ have plenty of them, in (my personal) reverse order
of information discoverability efficacy (cognitive overhead?):

  - IRC (logs): http://logs.guix.gnu.org/guix/
  - mailing lists, see: https://guix.gnu.org/en/contact/
  - videos: https://guix.gnu.org/en/videos/
  - wiki: https://libreplanet.org/wiki/Group:Guix
  - GNU manuals: https://gnu.org/manual
  - Cookbook: https://guix.gnu.org/cookbook/
  - GNU Guix Manual 1.4.0: https://guix.gnu.org/manual/en
  - GNU Guix Manual (Latest): https://guix.gnu.org/manual/devel/

Someone™ could help integrating useful information in one of the above
listed resources, for example informations like [1] and [2] should go to
"videos".

Each of the above listed help channels have very different contribution
workflows, ranging from chatting on IRC to sending a patch to include
Something™ in the cookbook or in the manual; this means that the more
Someone™ would like that information to traverse that list "upward", the
more will be the effort for Someone™ (Else™?) to add it...

It's a path and it's /also/ fractally recursive! :-D

For example, I have a feeling that many useful informations discussed in
this thread have been shared in previous messages on this mailing list
or IRC, wiki, videos... probably Someone™ shoud find a way to integrate
them /at least/ as a blog post in https://guix.gnu.org/en/blog/, if
Someone™ (Else™?) find it would be helpful in reducing the overhead to
do XYZ with/for Guix due to hard discoverability of that piece of useful
information; sometimes that piece of information is also /very/ useful
in reducing the cognitive overhead for contributors, that's recursivity
(© Simon Tournier).

To be cristal clear: I find that also "externally managed assets" - a
blog post, a video, a tool specifically designed for "Guix integration"
of tool XYZ, a Guix channel - **are** useful _contributions_, but that
kind of contributions are even harder to find and/or use if not properly
"integrated in Guix".

Happy hacking! Gio'

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

signature.asc
Description: PGP signature