Re: Guix Documentation Meetup

Re: Guix Documentation Meetup

[Blake Shaw]

hiya guix,

@cybersyn from IRC here, I recently contributed my first package, [notcurses]

--
tldr: is there also room to discuss contributing -- and possibly doing a
sizeable makeover to -- the *Guile* documentation? If so, I could give a
short 5 - 10 minutes presentation of what I think should be done (and
would volunteer to do).
--

I think I can personally offer a lot in terms of contributing to
documentation. While I don't serious experience w/technical writing,
prior to the pandemic I was doing my PhD in philosophy of mathematics,
so I come from a cross-disciplinary background that involves the often
difficult area of communicating new, formal ideas to previously
unexposed readers. I've also made a living as a new media artist since
2009, working mostly in C and C++ based frameworks, so I also have some
knowledge of the difficulties "crafters" have when learning new
development systems.

I don't know if this is the correct forum for it, but I personally think
the biggest documentation obstacle in Guix at the moment isn't so much
in Guix, but instead in Guile. I found Guix via SICP & Racket about a
year ago, and I remained a happy Racket hacker until a couple months ago
when I decided to devote my free time to learning Guile in hopes of
graduating to a Guix sensei one day.

While I've come to love Guile, compared to my experience with Racket its
been quite burdensome for me to get in the hang of, something I attribute
primarily to the structure of the docs, and not due to it being in any
way more difficult than Racket. While with Racket I was writing
useful programs in the standard #lang within my first week, with Guile
I often find that what should be almost trivial winds up with a lot of
time lost just trying to navigate and understand the docs. When I do
figure things out, it turns out to be no more difficult than the equivalent
in Racket, but a lack of consistency in the path that leads there in the
docs cause hangups, which has made trivial scripts that should take an hour
become weekend projects.

I know this isn't the Guile list, but when I've written on this topic in
the IRC I've had no response, which make me think docs could be a
bit of a bikeshedding topic in the community. But as Guile is
fundamental to Guix and theres a lot of crossover btwn the communities,
it seems like this could be a good time to raise these suggestions.

I've jotted down some notes on several concrete examples of where the docs
diverge from stylistic consistency, as well as some light analysis as to
why such seemingly small inconsistencies can lead to such hangups in the learning
process. If folks would be interested in me presenting a short 5-10min
presentation of these notes, I'd be happy to share.

Sorry for such a long-winded message! Personally, good documentation is
absolutely essential, and I feel like I could give Guile's docs a
serious makeover while I'm still at the early stage of my plunge and
have a perspective on the psychology of not-understanding -- something
that won't last long!

ez,
blake

-- 
“In girum imus nocte et consumimur igni”

Re: Guix Documentation Meetup

[Ryan Prior]

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

On Friday, December 10th, 2021 at 10:40 PM, Blake Shaw <blake@nonconstructivism.com> wrote:

> tldr: is there also room to discuss contributing -- and possibly doing a sizeable makeover to -- the Guile documentation?

Absolutely. The Guile docs are unusable and make Guile a pain to work with. I say this as an experienced lisp & scheme user with decades of experience now in elisp, racket, and clojure. After bouncing off of guile projects for years, last November I decided to do Advent of Code in Guile to force myself to finally get the hang of it & get productive. I gave up after a week, every task was unpleasant and I was reinventing basic language features because I couldn't find out where/if they were implemented in some obscure SRFI or ice-9 module. Like you wrote, the code I'd finally end up was fine, the language itself seems nice, but it's just plain inaccessible.

I've found the Guile IRC channel to be polite and encouraging, but also very self-satisfied, which makes it hard to feel heard as a Guile hacker who's struggling. I hesitate to tackle any kind of nontrivial problem with Guile because I have no confidence I will find tools that save me time; I'm proficient with a half dozen other languages, including multiple lisps, which provide much better support. So even though I really want to learn Guile,because of Guix, Shepherd and other cool software written in it, I'm no more likely to choose Guile for a software project today than I was 3 years ago when I just started learning it.

When I talk to experienced hackers in the Guile community I get the sense they've just accepted that yeah, the only way to get anywhere is to cold memorize the most popular ~80 SRFIs or implement everything you need yourself. One person I talked to was like "oh yeah Guile's great, you just have to implement your own standard library like I did."

I'd love to hear your talk, if you're up to present at the Guix meetup I'll definitely come and listen. I'm also happy to do what I can to help drive Guile adoption, create a great learning experience around it, and finally start to build the language community that Guile is lacking.

Cheers,
Ryan

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Ryan Prior <rprior@protonmail.com> writes:

> I've found the Guile IRC channel to be polite and encouraging, but also very
> self-satisfied, which makes it hard to feel heard as a Guile hacker who's
> struggling.

Consider reaching out to Andy Wingo (wingo in IRC in #guile). I hope I am not laying this issue at his feet by suggesting this, but I have interacted with him a handful of times, and he is a genuinely nice and helpful person, and also a guile maintainer. I am pretty confident he would want to help make this problem better -- especially if there are those willing to do some work.

Good luck! I have also found myself hunting around for basic functionality, and not being a guiler, nor even a schemer (I love lisps, but I mostly write emacs-lisp and common-lisp), wondering why things are fragmented into weird modules. It's a shame, because I feel like I would be contributing bigger features to Guix if I could stop bouncing off the language.

-- 
Katherine

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Blake Shaw <blake@nonconstructivism.com> writes:

> I'd love to know where you found trouble so that I can take that into
> consideration when developing a design strategy for the makeover.

When reading this, please keep in mind that I have a lot of gratitude for the various maintainers of this software and its respective documentation. Communication is very difficult, and relaying my experience and opinions is meant to convey that experience, and not to criticize anyone's efforts.

I think my frustration stems from the confluence of me not being familiar with scheme, how Guix writes scheme, how scheme the language and ecosystem work, the tools we have available to us, and then finally the documentation.

Not being a schemer (yet?), I can't speak with much authority, aside from the fact that I've written code in many languages, and most of these pain points are well addressed in others.

Usually, my frustrated workflow goes like this (warning: ignorance on display! :p):

- Identify something in Guix I want to do

- Open (or create) a file

- Start geiser

- Start writing Guile

- Come upon a semantic structure I want to write, and realize I don't know the
  Guile way to do it.
  
- In geiser, run =,a thing-i-want-to-look-for= (this is supposedly an apropos
  command that is supposed to search symbols for you). The command returns
  nothing. I realize I have to import the module implementing the thing I'm
  looking for first, thus defeating the purpose.

- Before, I would then go here[1] and try and textually search for the symbol.
  I have recently discovered the emacs function: =helm-info-guile= which makes
  searching a bit faster.

- Find that there are multiple, competing, modules which do the same thing in
  different ways.

- Realize I don't know which one to use, or which one Guix would prefer.

- Sometimes, realize that Guix has their own wrapper around one of the
  modules, and learn that something I thought was standard scheme is actually
  a Guix neologism.

- Import one and try it. Maybe import another and try it. Lose track of why
  I've imported things as I'm trying them because the module names have no
  indication of what they implement.

- Wish that Guix had a standard to prefix function calls with their module, as
  we do with =license:=.

- Have no way of automatically and programatically cleaning up imports to work
  around this.

- Forget what I was even trying to accomplish. Go to bed and try again
  tomorrow!

Specific to Guile documentation, I guess if I boil the above down, it would be something like:

Early in the documentation, directly address the intrinsic fragmentation of the scheme ecosystem, and how a new Guiler is meant to navigate that. Do so in terms that don't rely on experience with the Scheme ecosystem.

The Guile reference manual has this[2] section which, to me, is a paragraph which touches on this, and then much later has a blurb[3] on what SRFI is. I had no idea what =ice-9= was, and the first mention[5] of it in the manual is one of its modules. To my knowledge, what =ice-9= is, or why it's called that, is never addressed. It appears[5] I am not the first to be confused by this.

As a newcomer to Guile, and to scheme, I would expect Guile to give me its opinion of how to do things (i.e. which modules to prefer, what is considered "standard" in most schemes) until I've written enough Guile to form my own. As it's written, my impression is that the documentation relies on the reader knowing a lot about scheme coming in.

I feel there just needs to be an easier gradient for people trying to use Guile as their first scheme. It is not specifically Guile's problem, but as a service to its developers, the meta-topic should be addressed so a new developer is not left confused.

When we put a lot of work into something, it's really easy to fall in love with the idiosyncrasies of the thing, and to lose sight of what it's like to come into an ecosystem with no context. This can result in addressing things that feel important to us, the expert, but are really much further up the ladder of complexity.

When writing a landing page for a language, I feel the following is important:

*Don't overwhelm your newcomers.*
Your landing page should have few links, and they should directly address high-level questions:

- What am I looking at?
- How is what I'm looking at organized?
- What should people like me (e.g. non-programmers, programmers, schemers,
  people who don't speak English) be reading?
- A link to a site which provides easy to use symbol lookup.

The documentation can fan out in complexity from there, but the landing page must not be overwhelming.

Anyway, those are my opinions :)

[1] - https://www.gnu.org/software/guile/manual/guile.html
[2] - https://www.gnu.org/software/guile/manual/guile.html#Guile-Scheme
[3] - https://www.gnu.org/software/guile/manual/guile.html#SRFI-Support
[4] - https://www.gnu.org/software/guile/manual/guile.html#ice_002d9-optargs
[5] - https://lists.gnu.org/archive/html/guile-devel/2010-07/msg00045.html

-- 
Katherine

Re: Guix Documentation Meetup

[zimoun]

Hi,

On Sat, 11 Dec 2021 at 05:40, Blake Shaw <blake@nonconstructivism.com> wrote:

> --
> tldr: is there also room to discuss contributing -- and possibly doing a
> sizeable makeover to -- the *Guile* documentation? If so, I could give a
> short 5 - 10 minutes presentation of what I think should be done (and
> would volunteer to do).
> --

Cool!

Minor comments trying to feed this worth proposal.


> I don't know if this is the correct forum for it, but I personally think
> the biggest documentation obstacle in Guix at the moment isn't so much
> in Guix, but instead in Guile. I found Guix via SICP & Racket about a
> year ago, and I remained a happy Racket hacker until a couple months ago
> when I decided to devote my free time to learning Guile in hopes of
> graduating to a Guix sensei one day.

I agree that the learning path in Guile land is not always smooth.
However, I do not think mastering Guile and/or its specificity is a
requirement to be a “Guix sensei”.  Obviously, better Guile
documentation improves the ecosystem, then it is an overall better. :-)


> While I've come to love Guile, compared to my experience with Racket its
> been quite burdensome for me to get in the hang of, something I attribute
> primarily to the structure of the docs, and not due to it being in any
> way more difficult than Racket. While with Racket I was writing
> useful programs in the standard #lang within my first week, with Guile
> I often find that what should be almost trivial winds up with a lot of
> time lost just trying to navigate and understand the docs. When I do
> figure things out, it turns out to be no more difficult than the equivalent
> in Racket, but a lack of consistency in the path that leads there in the
> docs cause hangups, which has made trivial scripts that should take an hour
> become weekend projects.

Well, I am not convinced it is because the structure of the docs.
Instead, I think it is because it is missing docs. :-)

If we compare apple to apple, here are the entry points:

    https://docs.racket-lang.org/
    https://www.gnu.org/software/guile/learn/

and so the Guile manual

    https://www.gnu.org/software/guile/manual/guile.html

is a reference manual, which correspond to, mainly

    https://docs.racket-lang.org/reference/

and also,

    https://docs.racket-lang.org/guide/

I am not convinced you started Racket by these ones. ;-)

Indeed, one document on the Guile side vs two documents on Racket side;
the Guile manual could be split, I do not know if the core issue here.
Instead, IMHO, what is missing are all the others. :-) For instance,

    https://htdp.org/

which is a really smooth introduction.  Somehow, it appears to me
that it is missing an introduction, a similar document as,

     https://www.gnu.org/software/emacs/manual/html_mono/eintr.html


> I know this isn't the Guile list, but when I've written on this topic in
> the IRC I've had no response, which make me think docs could be a
> bit of a bikeshedding topic in the community. But as Guile is
> fundamental to Guix and theres a lot of crossover btwn the communities,
> it seems like this could be a good time to raise these suggestions.

I agree.  For what it is worth, I tried once to quickly explain monad,
with the aim of “Store Monad“ in mind,

    https://guix.gnu.org/manual/devel/en/guix.html#The-Store-Monad

After several discussions with strong Guix hackers, it appears to me
that they missed the general concept of monad, at least it was vague.
Therefore, I tried to write a simple explanation,

    https://simon.tournier.info/posts/2021-02-03-monad.html

Bah, the other part has never seen the light, another story. :-)  Long
time ago, Pierre wrote down a quick introduction to Scheme, which ended
into the Cookbook,

    https://guix.gnu.org/cookbook/en/guix-cookbook.html#Scheme-tutorials

From my point of view, the missing documentation is the one between
newcomer and Reference manual.  For instance, setup a Guix/Guile
environment is not straightforward; Geiser helps, but even after some
time, I am often still fighting against it, and I do not know what
exists outside the Emacs world.


On the Guile land, one feature which really annoys me is the poor
discoverability from REPL; for an instance,

--8<---------------cut here---------------start------------->8---
$ guix repl
scheme@(guix-user)> ,a fold-packages
scheme@(guix-user)> ,use(gnu packages)
scheme@(guix-user)> ,a fold-packages
(gnu packages): fold-packages	#<procedure fold-packages (proc init #:optional modules #:key select?)>
scheme@(guix-user)> ,d fold-packages
Call (PROC PACKAGE RESULT) for each available package defined in one of
MODULES that matches SELECT?, using INIT as the initial value of RESULT.  It
is guaranteed to never traverse the same package twice.
--8<---------------cut here---------------end--------------->8---

well, IPython, GHCi, UTop (to name some I use) provide a complete
different experience.  Well, maybe resuming this discussion [1] is
worth.

1: <https://yhetil.org/guix/86d00evkmr.fsf@gmail.com/>


> I've jotted down some notes on several concrete examples of where the docs
> diverge from stylistic consistency, as well as some light analysis as to
> why such seemingly small inconsistencies can lead to such hangups in the learning
> process. If folks would be interested in me presenting a short 5-10min
> presentation of these notes, I'd be happy to share.

I would be interested to listen your ideas, here, there or overthere. :-)


Cheers,
simon

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Here is some analysis on various popular languages' documentation landing pages. I did this on Sunday, but I held it back from my previous message because it was already quite long, and I was worried this would be seen as over-critical and maybe raise the ire of various language fans.

But I think it might add to the conversation and help create better Guile documentation, so I'll risk it :)

For context, the only language on this list I really know well is Go.

Guile:
======
- Tutorial for extending a C program with Guile
- The manual
- Scheme Resources
  - "The Revised^6 Report on the Algorithmic Language Scheme"
  - "" but 7
  - "" but 5
  - (more links that IMO are only meaningful if you already know Scheme)

Overall, I'm left feeling like I have a clear sense of direction because it's apparent to me that I should click through to the reference manual. Experience with the GNU ecosystem helps here. I am left wondering whether I should click on any of the other links, and what I might be missing by not doing so. But clicking through reveals lengthy documents that I don't know if I should read yet or not.

Once I do click through to the manual, I am in a pretty familiar GNU document, and the other comments about this document become applicable.

The one thing I would add here is that other languages have a separate symbol/library explorer with a few more bells and whistles to support jumping around. It would be nice if Guile not only curated opinions on which modules to use, but used a separate, more featureful site for that.

Go (https://go.dev/doc/):
=========================
- A blurb trying to sell Go
- A link on how to install Go
- Links to tutorials and opinions on how to write Go.
- Links for very specific topics like editor plugins and fuzzing.

Overall, this seems cluttered and disorganized. For some reason there are several links to tutorials on very specific topics before there is a link to look at the packages in the standard library. These tutorials seem to be interspersed with more fundamental, important, beginner topics, and I'm not sure why.

The link to look at the documentation for the standard library -- something a developer will be working with a lot -- is titled "Package Documentation", too generic a term.

Once I do click through, there is a great site for navigating the standard library which explains what packages are for, and provides various navigation elements for jumping around.

Rust (https://www.rust-lang.org/learn):
=======================================
- A link to a book
- A link to a course
- A link to rust by example
(note the support for 3 different kinds of learning styles)
- Core documentation
  - The standard library (here is, by way of being the standard library, an
    opinion I can borrow for how things are done).
  - (more links I skipped because I don't know rust, and I"d start with the
    above)

Overall, I am left feeling like I know where I would start depending on how I want to learn, and have a quick reference to the standard library's API.

Once I click through to the standard library, it suggests to me how to read it, and addresses the meta-question of what I'm looking at. I haven't used this site, but clicking around, it appears to have decent navigation elements for jumping around.

Python (https://www.python.org/doc/):
=====================================
- A blurb on how the different ways to consume the documentation.
- Links grouped by self-reported expertise with the language

If I click on Beginner's guide:

- Link to explanation of what Python is
- Blurb on how to get Python
- Links for non-programmers to learn
- Links for programmers to learn
  - Acknowledgment that I've been reading wiki pages. I now have an
    explanation for why what I've been reading feels cobbled together.
  - A link to a separate beginner's guide overview with more general
    information about the language.
  - A long list of books, websites, and tutorials (note there is no opinion
    given on which I should begin with)

Overall, I am left feeling overwhelmed, and like I must independently find a curated tutorial which will give me opinions I can use until I can form my own.

But wait! Had I clicked on "Python Docs" instead of "Beginner's Guide", I get something much easier to consume:

- A Tutorial which simply states "start here". As a newbie, OK!
  - This looks like a book
- Library reference
- Language reference
- General links to support usage

This is not overwhelming, and I feel like I have a small enough set of options to click through that I can find what I need. Further, it looks like a curated opinion of how I should do things, and in what order.

-- 
Katherine

Re: Guix Documentation Meetup

[Luis Felipe]

[-- Attachment #1.1: Type: text/plain, Size: 1762 bytes --]

Hi,

On Tuesday, December 14th, 2021 at 4:01 PM, Katherine Cox-Buday <cox.katherine.e@gmail.com> wrote:

> Guile:
> 

> -   Tutorial for extending a C program with Guile
> -   The manual
> -   Scheme Resources
>     -   "The Revised^6 Report on the Algorithmic Language Scheme"
>     -   "" but 7
>     -   "" but 5
>     -   (more links that IMO are only meaningful if you already know Scheme)

For what it's worth, the intention with the structure of the Learn section was to put first introductory, prescriptive documentation about the language and what is possible to do with it. So:

+ Tutorials (Guides, etc.)
+ Reference manuals
+ Scheme resources

This documentation was supposed to fill some of the gaps that have been already mentioned in this thread and other previous conversations during the years in other channels. Unfortunately, the Tutorials section hasn't seen any additions since the day the website design was updated.

To me, the idea was to focus on building the Tutorials section gradually because, I thought, the reference and Scheme resources were relatively complete (except for the discoverability of SRFIs and how to use them in your own project when they don't come with Guile). I suggested something like this for tutorials:

+ Hello Guile: Getting Started (An overview of programming, and how to start 

with Guile)
+ Hello Guile: Let's develop a console application
+ Hello Guile: Let's develop a desktop application
+ Hello Guile: Let's develop a web application
+ Hello Guile: Let's develop a 2D game
+ Hello Guile: Let's package your software for distribution (with Guix)

I guess it is a matter of filling the blanks, which is a lot of work you have to enjoy doing and have enough time to do.

[-- Attachment #1.2: publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc --]
[-- Type: application/pgp-keys, Size: 1815 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 509 bytes --]

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

Luis Felipe <luis.felipe.la@protonmail.com> writes:

> Hi,

Hello! Thank you for adding some context around why things are laid out the way they are.

I just wanted to respond again with gratitude for your work, and to plainly state that I view this work as difficult, with no clear best practice.

Sincerely,
-- 
Katherine

Guile documentation

[Ludovic Courtès]

Hi Blake,

Blake Shaw <blake@nonconstructivism.com> skribis:

> While I've come to love Guile, compared to my experience with Racket its
> been quite burdensome for me to get in the hang of, something I attribute
> primarily to the structure of the docs, and not due to it being in any
> way more difficult than Racket. While with Racket I was writing
> useful programs in the standard #lang within my first week, with Guile
> I often find that what should be almost trivial winds up with a lot of
> time lost just trying to navigate and understand the docs. When I do
> figure things out, it turns out to be no more difficult than the equivalent
> in Racket, but a lack of consistency in the path that leads there in the
> docs cause hangups, which has made trivial scripts that should take an hour
> become weekend projects.

IWBN if we could take advantage of your fresh eye to restructure the
Guile manual in a way that makes it more convenient.

Guile has changed a lot since the manual was initially written, a lot of
sections were added, some removed, but we probably didn’t take the time
to sit down and see how to restructure it accordingly.

So if you have a specific structure in mind, or if you remember
precisely what was hard to find and located in a unexpected section,
please let’s take advantage of that!

Thanks,
Ludo’.

Re: Guix Documentation Meetup

[adriano]

Il giorno sab, 11/12/2021 alle 05.40 +0700, Blake Shaw ha scritto:
> 
> hiya guix,
> 
> @cybersyn from IRC here, I recently contributed my first package,
> [notcurses]
> 
> --
> tldr: is there also room to discuss contributing -- and possibly
> doing a
> sizeable makeover to -- the *Guile* documentation? If so, I could
> give a
> short 5 - 10 minutes presentation of what I think should be done (and
> would volunteer to do).
> --

I'm reading this on december 21st

I suppose the documentation meetup happened already and I don't know if
you gave your illustration of your notes

I, for one, would LOVE to hear it

Yes the Guile experience is abysmal, awful, actively rejecting
beginners/newcomers

I've been wandering in the Guile manual, on and off, for years now and
I still can't make any sense of it

If I have a curiosity I still can't find my way around to such thing in
the manual, most of my discoveries have been by pure chance

Often, I try to re-read the same thing a few months later and I can't
find it again

Everytime I attempted something in Guile I've been frustrated

I myself have done a so called vlog where I show how to read a file in
Guile

I also have a general view of packaging and distributing Guile packages
that I gained by some very hard work that lasted a couple of years but
I was discouraged in doing more videos

Not only previous knowledge of the GNU system is a not declared hard
requirement

Often, previous knowledge of other things is required too

For example the new exceptions system is obscure, you're required to
know the one from Common Lisp in order to undertsand the one in Guile

Or,as another example, I stumbled in an example made in python of a
hashmap (similar to the ones very common in Clojure) and I got that

Good luck with data structured in Scheme

Or, the machinery for manipulating xml (and json ?) trees is discussed
in academic (!!) papers that present the code in Haskell, so you need
to learn Haskell in order to read that

The curse of knowledge in the Guile world is tragic



> I think I can personally offer a lot in terms of contributing to
> documentation. While I don't serious experience w/technical writing,
> prior to the pandemic I was doing my PhD in philosophy of
> mathematics,
> so I come from a cross-disciplinary background that involves the
> often
> difficult area of communicating new, formal ideas to previously
> unexposed readers. I've also made a living as a new media artist
> since
> 2009, working mostly in C and C++ based frameworks, so I also have
> some
> knowledge of the difficulties "crafters" have when learning new
> development systems.

That's all good. I love that you noticed the problem and are offering a
fresh perspective 

> I don't know if this is the correct forum for it, but I personally
> think
> the biggest documentation obstacle in Guix at the moment isn't so
> much
> in Guix, but instead in Guile. 

Absolutely, yes

> I found Guix via SICP & Racket about a
> year ago, and I remained a happy Racket hacker until a couple months
> ago
> when I decided to devote my free time to learning Guile in hopes of
> graduating to a Guix sensei one day.

Not only a Guix sensei but maybe a Guile sensei

Why has Guile only Guix ?

Why couldn't we have more nice things made in Guile ?

> While I've come to love Guile, compared to my experience with Racket
> its
> been quite burdensome for me to get in the hang of, something I
> attribute
> primarily to the structure of the docs, and not due to it being in
> any
> way more difficult than Racket. While with Racket I was writing
> useful programs in the standard #lang within my first week, with
> Guile
> I often find that what should be almost trivial winds up with a lot
> of
> time lost just trying to navigate and understand the docs. When I do
> figure things out, it turns out to be no more difficult than the
> equivalent
> in Racket, but a lack of consistency in the path that leads there in
> the
> docs cause hangups, which has made trivial scripts that should take
> an hour
> become weekend projects.
> 
> I know this isn't the Guile list, but when I've written on this topic
> in
> the IRC I've had no response, which make me think docs could be a
> bit of a bikeshedding topic in the community. But as Guile is
> fundamental to Guix and theres a lot of crossover btwn the
> communities,
> it seems like this could be a good time to raise these suggestions.

Oh I love this !

> I've jotted down some notes on several concrete examples of where the
> docs
> diverge from stylistic consistency, as well as some light analysis as
> to
> why such seemingly small inconsistencies can lead to such hangups in
> the learning
> process. If folks would be interested in me presenting a short 5-
> 10min
> presentation of these notes, I'd be happy to share.

yes pleeeease !!!


> Sorry for such a long-winded message! Personally, good documentation
> is
> absolutely essential, and I feel like I could give Guile's docs a
> serious makeover while I'm still at the early stage of my plunge and
> have a perspective on the psychology of not-understanding --
> something
> that won't last long!

Oh God, did you give this talk ?

Is a recordng available ?

If it's not, you should make a vlog !

Please !

> 
> ez,
> blake
> 

Re: Guile documentation

[Blake Shaw]

[-- Attachment #1: Type: text/plain, Size: 2018 bytes --]

Hi Ludo,

(replying to this email from my other email address because I can't seem to
find it in gnus, which I only recently switched to)

For sure. I'm preparing a little document that provides an analysis of pain
points in the docs, which I'll hopefully have done by the end of this week
and can send to the group. I'll be mostly focused on the general
organizational structure of the docs and will offer solutions that if
everyone agrees to I'll go ahead and start putting to work.

Ez,
Blake

On Tue, Dec 21, 2021, 01:57 Ludovic Courtès <ludo@gnu.org> wrote:

> Hi Blake,
>
> Blake Shaw <blake@nonconstructivism.com> skribis:
>
> > While I've come to love Guile, compared to my experience with Racket its
> > been quite burdensome for me to get in the hang of, something I attribute
> > primarily to the structure of the docs, and not due to it being in any
> > way more difficult than Racket. While with Racket I was writing
> > useful programs in the standard #lang within my first week, with Guile
> > I often find that what should be almost trivial winds up with a lot of
> > time lost just trying to navigate and understand the docs. When I do
> > figure things out, it turns out to be no more difficult than the
> equivalent
> > in Racket, but a lack of consistency in the path that leads there in the
> > docs cause hangups, which has made trivial scripts that should take an
> hour
> > become weekend projects.
>
> IWBN if we could take advantage of your fresh eye to restructure the
> Guile manual in a way that makes it more convenient.
>
> Guile has changed a lot since the manual was initially written, a lot of
> sections were added, some removed, but we probably didn’t take the time
> to sit down and see how to restructure it accordingly.
>
> So if you have a specific structure in mind, or if you remember
> precisely what was hard to find and located in a unexpected section,
> please let’s take advantage of that!
>
> Thanks,
> Ludo’.
>
>

[-- Attachment #2: Type: text/html, Size: 2622 bytes --]

Re: Guix Documentation Meetup

[adriano]

Il giorno dom, 12/12/2021 alle 21.50 -0600, Katherine Cox-Buday ha
scritto:



> - In geiser, run =,a thing-i-want-to-look-for= (this is supposedly an
> apropos
>   command that is supposed to search symbols for you). The command
> returns
>   nothing. I realize I have to import the module implementing the
> thing I'm
>   looking for first, thus defeating the purpose.

about this, I want to report an example

scheme@(guile-user)> (help tail)
Did not find any object named `tail'
scheme@(guile-user)> 


BUT


scheme@(guile-user)> (help "tail") <-- notice the quotation marks !
Documentation found for:
(language cps): $ktail
(language tree-il): seq-tail
(language tree-il): abort-tail
(guile): list-tail
(guile): make-struct/no-tail
(srfi srfi-1): find-tail
(system vm assembler): emit-tail-call-label
(system vm assembler): emit-tail-call
(system vm assembler): emit-tail-pointer-ref/immediate
(ice-9 vlist): vlist-tail

`$ktail' is an object in the (language cps) module.

- Variable: $ktail


`seq-tail' is a procedure in the (language tree-il) module.

- Variable: seq-tail


`abort-tail' is a procedure in the (language tree-il) module.

- Variable: abort-tail


`list-tail' is a procedure in the (guile) module.

- Function: list-tail _ _
     - Scheme Procedure: list-tail lst k
     
     
          Return the "tail" of LST beginning with its Kth element.  The
first
          element of the list is considered to be element 0.
     
          `list-tail' and `list-cdr-ref' are identical.  It may help to
think
          of `list-cdr-ref' as accessing the Kth cdr of the list, or
          returning the results of cdring K times down LST.



`make-struct/no-tail' is a procedure in the (guile) module.

- Function: make-struct/no-tail _ .  _
     - Scheme Procedure: make-struct/no-tail vtable .  init
          Create a new structure.
     
          VTABLE must be a vtable structure (see Vtables).
     
          The INIT1, ... are optional arguments describing how
successive
          fields of the structure should be initialized.  Note that
hidden
          fields (those with protection 'h') have to be manually set.
     
          If fewer optional arguments than initializable fields are
supplied,
          fields of type 'p' get default value #f while fields of type
'u'
          are initialized to 0.



`find-tail' is a procedure in the (srfi srfi-1) module.

- Function: find-tail pred lst
     Return the first pair of LST whose CAR satisfies the predicate
     PRED, or return `#f' if no such element is found.



`emit-tail-call-label' is a procedure in the (system vm assembler)
module.

- Function: emit-tail-call-label asm t-ff72ee5a3696d21-378b


`emit-tail-call' is a procedure in the (system vm assembler) module.

- Function: emit-tail-call asm


`emit-tail-pointer-ref/immediate' is a procedure in the (system vm
assembler) module.

- Function: emit-tail-pointer-ref/immediate asm t-ff72ee5a3696d21-3ac6
t-ff72ee5a3696d21-3ac7 t-ff72ee5a3696d21-3ac8


`vlist-tail' is a procedure in the (ice-9 vlist) module.

- Function: vlist-tail vlist
     Return the tail of VLIST.


That is, help with the quotation marks reports about things even if
they're in namespaces you haven't imported yet !


I'm confused about the difference between help withouth and with the
quotation marks

In fact

scheme@(guile-user)> ,a tail
(guile): list-tail	#<procedure list-tail (_ _)>
(guile): make-struct/no-tail	#<procedure make-struct/no-tail (_ .
_)>


apropos does find at least something, but

scheme@(guile-user)> (help tail)
Did not find any object named `tail'


help with no quotation marks finds nothing !

Why is this so ?

I can't fathom that ¯\_(ツ)_/¯

And I can't even remember how I discovered this behaviour

I remember I was quite puzzled when I did

This is hidden and arbitrary

But it IS like that !

So maybe this little trick can make your sessions a bit less
frustrating !

"tail" was just a silly example I was able to come up with

I'd be curious to try with some of your things :-)

Bye
Adriano

Re: Guix Documentation Meetup

[Katherine Cox-Buday]

adriano <randomlooser@riseup.net> writes:

> Il giorno dom, 12/12/2021 alle 21.50 -0600, Katherine Cox-Buday ha scritto:

>> - In geiser, run =,a thing-i-want-to-look-for= (this is supposedly an
>> apropos command that is supposed to search symbols for you). The command
>> returns nothing.

> about this, I want to report an example
>
> scheme@(guile-user)> (help tail)
> Did not find any object named `tail'
> scheme@(guile-user)> 
>
> BUT
>
> scheme@(guile-user)> (help "tail") <-- notice the quotation marks !
> Documentation found for:

> That is, help with the quotation marks reports about things even if
> they're in namespaces you haven't imported yet !

Thank you very much for the tip! I will definitely be trying this next time I'm hacking on Guile!

-- 
Katherine