Re: GNU Guix 1.4.0 released

[indieterminacy <indieterminacy@libre.brussels>]

On 03-01-2023 19:42, Joshua Branson wrote:
> indieterminacy <indieterminacy@libre.brussels> writes:
> 
>> On 03-01-2023 10:08, Ludovic Courtès wrote:
>>> Hi!
>>> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>>> 
>>>> Congrats, and yay!  It's a hell of a release! :-) Let's try to make 
>>>> more
>>>> punctual ones from now on, and also try to lower the amount of 
>>>> manual
>>>> labor producing one incurs (by streamlining the process), as 
>>>> speaking
>>>> for me, this was one of the reasons I kept putting it back.
>>> Definitely, let’s see how we can make the process smoother.
>>> In my experience though, a lot of the work is coordination: keeping
>>> track of what needs to be done, open bugs, calling for testing, etc.
>>> I think we should start thinking about the next release, forming a
>>> small release team, and I’ll be happy to mentor!
>>> Thanks,
>>> Ludo’.
>> 
>> Out of curiosity, have you ever approached developing a release from 
>> the
>> perspective of doing documentation first?
>> 
>> For example, test driven approaches like BDD or TDD have allowed the
>> expectations and examples to be worked out first and the the 
>> implementation
>> built to form it.
>> 
>> More practically, theres a recent thread concerning different 
>> approaches and
>> priorities concerning syntaxes. Also, if during 1.5 there were 
>> articulations
>> regarding how existing behaviour does not conform with desired 
>> behaviour then it
>> may become easier to divide up tasks into chunks for teams or 
>> individuals to
>> work on.
>> 
>> With idealised documentation in place this could provide a point of 
>> motivation
>> for developers and avoid any fatigue once the solution is in place as 
>> the
>> /drudgery/ of explaining how things work and how they can be used had 
>> been
>> worked out in advance.
> 
> What areas does guix need more documentation?  To answer that question
> for myself, I might say more gexp examples.  Though unmatched-paren is
> working on a series of blog posts to dive really deep into that topic.
> 

Over the years in general (ie for whatevever in programming), I tend to 
find documentation examples to provide the easiest way of explaining 
things and this can create shortcomings as creating or maintenan
FWIW, I always need multiple examples for any programming domain but 
this was not the point I was trying to make.
(in any case I learn systems through breaking them, it tends to give me 
a better understanding of systems).

For an idea about documenting before a project, it may be good to create 
diagrams,
as some (like myself) are visually orientated.
Not only can it be a visual assistance, it can also aid recall.
In terms of a project, this may widen the talent pool and improve 
alignment.

>> In any case, while I cannot comment on the tactics within the OpenBSD 
>> community
>> I always considered it a noble thing that no improvements we put into 
>> their OS
>> until the features were correctly documented.
>> 
> 
> While OpenBSD does a pretty good job of documenting everything, I would
> also chime in and say that Guix does a fantastic job of translating the
> existing documentation into other languages. What do we have
> documentation in English, German, French, and significant parts in
> Russian and some asian languages. That's pretty stellar!
> 
Yes, indeed!

Seeing this talk in Paris made it very clear how much this is being 
treated seriously.
https://10years.guix.gnu.org/program/#let-s-translate-guix-together-

Thanks for making this point.

Perhaps some people from different language communities require 
assistance in order to build
next generation Guix functionality.
It may be worth lowering the cost of them articulating their needs, 
including
which section within the documentation requires focus for a specific 
language.

>> 
>> Thanks everybody with your work on 1.4.0 !

-- 
Jonathan McHugh
indieterminacy@libre.brussels