IRC channel logs
2022-11-23.log
back to list of logs
<rekado>I was thinking we might benefit from more clearly separating the reference part from the prose <civodul>for some reason goggles-bot was stuck in scm_read_line on a TLS record port <zimoun>Well, I think it is a good writting practise to keep clear what is «learning-oriented», «information-oriented» and «problem-oriented». All can be in the same document though. <civodul>ACTION is wary of "should" and "should not" :-) <civodul>i'm not sure all four things need to be separate <rekado>it’s been a long time since I read the manual front to back <rekado>so I often use the index, and I jump right into some section <rekado>and then I find myself lost in the midst of a bunch of service references <zimoun>civodul: I think it is better from a learning point of view to have four things separated. All be be in the same document. <rekado>those reference sections generally have very little … prosaic value <zimoun>For instance, «Getting Started» is kind of tutorial and «Store monad» kind of explanation, etc. <zimoun>But each section should be written with one goal and target audience in mind. <zimoun>rekado: yeah for sure. The border is never clear. But I recommend the “Analogy from cooking”. It gives an idea about the intent for these 4 distinctions. <zimoun>For instance, if we speak about break, you can be interested only by “how to bake it” and not interested by how chemistery works (explanation). <zimoun>A good documentation has all 4 types. Because we need one or the other depending on the mood, the level of expertise, etc. <zimoun>speak about bread, not break ;-) <civodul>i wonder about the implications of separating explanations <zimoun>I agree. To me, explanations are distilled (maybe the correct word is disseminated ;-)) in the 3 other types. <zimoun>Well, when speaking about class, we have lesson with blackboard (reference), exercises (tutorial), and labs (how to). The explanations are: repeat again and again and again. ;-) Well, from my experience about teaching. <rekado>it’s an analogy, but I always thought of the book to be the reference and the blackboard session to be the how to. <rekado>civodul: I think we’re not too far from keeping things separate <rekado>we already have an extensive reference section <rekado>I guess the whole manual just needs a few editing passes to improve reading flow and maybe move some asides to chapters (and expand them there) <civodul>rekado: maybe; i don't have a clear vision of what the right sectioning would look like <zimoun>the two that I pointed earlier look at the wrong place. As in their own island when one should not be part of the Guix manual and the other should move under an already existing section <zimoun>Debbuging should go to Developpement chapter, close to GCC toolchain <civodul>well, "Getting Started" is a bit different; i purposefully put it right at the beginning, in its own chapter <civodul>because that's what you want people to see first <rekado>I agree with that reasoning, for what it’s worth. <rekado>I also don’t think the manual should be gutted of all prose <rekado>in fact, I like the reference sections the least. <rekado>but perhaps there’s a way for Maxwell’s daemon (if it isn’t too busy already) to separate the two a little more where they have mixed a little too much <zimoun>civodul: will «guix shell python python-numpy --with-c-toolchain=python=gcc-toolchain@8» recompile all the Python stack (python-numpy included) with GCC@8 instead of default (GCC@10, I guess)? <civodul>rekado: yes, that makes sense to me; for instance i'm not satisfied with most of the "Invoking" nodes <civodul>like, we'd need real prose to illustrate "guix package" and "guix shell" <civodul>as opposed to a couple of paragraphs at the top of "Invoking" <zimoun>well, it is confusing with «Dependency-free so that the runtime library (which is written in pure C)» <civodul>weird, the bit i looked at looked like C++ <zimoun>I think src/parser.c is generated by Node <zimoun>from my understanding, src/parser.c which is then used is generated from grammar.js. <zimoun>containing the “dependencies-free” parser written in C. <zimoun>Maybe I am wrong. Or let enjoy the new kidkool stuff. ;-)