Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal

[Neil Jerram]

Hi Blake,

On Tue, 8 Feb 2022 at 08:55, Blake Shaw <blake@nonconstructivism.com> wrote:
> [...]
>
> Serving at once as a referrence manual & API specification, the large size 
> may in part be attributed to what simultaneously makes Guile an appealing 
> project to contribute to, while also rendering the documentation process 
> somewhat delicate: Guile is a massive collective project featuring the 
> contributions of many authors over the course of three decades, contributions 
> which Guilers would hate to trivialize or treat as insignificant or edit away 
> on a whim. Additionally, Guile comes from a long set of traditions within 
> Scheme hacking which itself is deep with sage wisdom spanning many 
> pedagogical philosophies and one of the greatest literature traditions of 
> hacker culture. Is it possible to perform a makeover of the Guile 
> Documentation while respecting these historical threads, at once rendering it 
> more approachable for new users while not forsaking the deep nuggets of 
> wisdom that lie therein?
>
> Since mid-December I have been mulling over these questions as newcomer, both 
> studying & analyzing the docs, and trying to come to grips with it's 
> strengths and shortcomings. For this talk, I will present my research to the 
> Guix community, culminating with a plan for a full makeover of the existing 
> docs which would respect the above concerns. I will use the 5 minute 
> presentation to focus on the plan of action, with hopes that during the Q&A 
> we can come to consensus on what is to be done. The decisions made by the 
> group will form the basis of a proposal to be made to the Guile community, 
> and once everyone is in agreement with plans for how to move forward I will 
> undertake the effort to implement the makeover proposal.

Speaking as one of the past authors of the manual, I look forward to
hearing your thoughts.  It is genuinely challenging to present this
amount of material and explain its complexity, and there is no reason
at all to consider any current arrangement as cast in stone.  Thanks
for thinking about this.

Best wishes,
    Neil