Improving the README and new user experience

Improving the README and new user experience

[swedebugia]

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

Hi

I would like to propose a rewrite of the README.

I'm wondering if it would be best to split it up in 2 files. 

One for guix and one for guixsd. 

I would like to help new users understand more about GuixSD before they run it (and inevitably into errors) 

Users come from other Distros where tough package manager errors mostly mean: you are screwed, reinstall. Because if you loose the central command to manipulate the system - how can you possibly recover? Imagine apt being corrupt or gone missing. 

So when we have strong reactions to users used to being screwed and reinstall then we need to educate them that this is something completely different where it is actually hard to break (besides when running guix pull and not understanding how to set paths manually) 

Another example:
The current parsing of config.scm is eh... crude and might work for seasoned programmers who know the exact differences between parameters, instantiated config, where inherit works (record types) and where they don't (service-types), what a service object is, how you remove an item from a list of service objects, etc. 

I would like to tell new users NOT to change the config.scm at first install if they are not confident schemers. (besides the username and timezone perhaps). 

Also the editors included in the image are crap because they lack two important features: 1) keeping track of the damn paranteses and 2) comment and uncomment region. 

Edits to the configuration is in my view best done with small incremental steps in emacs and validating the config for each step (side note how do you validate your config from within emacs?). Access to irc to ask for questions/help when guix sometime spews incomprehensible errors at you is also advisable.

We also need a lot more complete examples of working snippets and whole config.scms to add to a config in the lack of good error reporting. 

Maybe a list of links to working configs from community members would be good to add Somewhere. I learned a lot from reading the
Config of others. Perhaps in a new file called GUIXSD-CONFIGURATION-EXAMPLES? 

I saw that some of you, Alex, sidesteps the removal of service objects-problem by defining all the services yourself in a list instead. 

-- 
Cheers Swedebugia 

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

Re: Improving the README and new user experience

[Dan Partelly]

HI,

When somebody installs an OS , the last thing he wants is to have the OS craps on him in the next 10 minutes. And I can safely generalize this. People want to install the OS and then get on with their lives, do their work or whatever else. This is paramount for an OS. Be reliable and get out of the way. GuixSD unfortunately falls short here , but some aspects are easy to mitigate. This assumes that you want people to use your OS, and it’s not written by developers for developers only. Adoption of software is modulated by social factors much more then technical excellence. If somebody wants his tools

> I would like to help new users understand more about GuixSD before they run it (and inevitably into errors) 

First thing, you must ensure that users do not run in the errors. If the users go inevitably into errors, then you have an issue with the design of the system and you have to rethink it. The simplest best way to mitigate this aspect is two fold:
	- make a FAQ page as the first thing of the manual. Make sure it contains a glossary of specific terms such as  store, system profile, user profile, derivation, substitutes, explain structure, and some usual commands. Make sure it has a disclaimer the system is in beta, and may break, outlining the simplest way to recover. 
       - make sure you follow sane development practices and relase engineering. Take this very seriously. By no means have giux pull work by pulling from the bleeding edge of a  repository. In my opinion this is irresponsible. You just exposed your users to every bug imaginable in a development cycle. Guix is inevitably rolling, and to get last packages  you have to update it, but do this from intermediary branches such as 0.14.1 … 0.14.n, branches which where regression  tested before beeing inflicted upon the user. 

> Users come from other Distros where tough package manager errors mostly mean: you are screwed, reinstall. Because if you loose the central command to manipulate the system - how can you possibly recover? Imagine apt being corrupt or gone missing. 

This is not true. In classical distros, the central command to recover is not the package manager per se. It’s an editor in the first place, and only secondary the package manager. You are not screwed if the package manager craps on you, you have a lot of options to recover. You do not have to reinstall. Guix is much more central to GuixSD then pacman to arch for example, because well, it also wants to manage t system configuration for you, not just install some packages. 

> wen we need to educate them that this is something completely different where it is actually hard to break (besides when running guix pull and not understanding how to set paths manually) 

What you want is not easy recovery. This is important , but secondary to the fact that they **system should not break** in the first place.  guix pull is a very problematic command. Users do not want to do a command which supposedly gives them access to new packages and then have to recover. Again, user want to get the software, and get on with their lives. This means that you must have guix pull work flawlessly (industrial strength ) by the time you reach 1.0 I cannot stress enough how important this is for the adoption of your OS.

> I would like to tell new users NOT to change the config.scm at first install if they are not confident schemers. (besides the username and timezone perhaps). 

I dont think it’s OK. People want to configure the system. With how much fragmentation exist in Linux world it is unlikely you will be able to offer a good inital configuration which satisfy ppl coming from othe Linuxes. For example the default bare bones loaded a DNS caching demon for me. Why would I want that ? The config system should as user friendly as possible, and ***DOCUMENTED**.  FAQ are in order:

 - how to I modify the base packages set
 - how do I add my own package set
 - how do I alter a package build options
 -what can be inherited and what not, and what inheriting gains me
 - how do I set timezone , locale
 - how do I create a network interface. use DHCP, fixed address. How do I create abridge network interface 
 - boot and initrd handling. Add new drenel driver to kmod Options for init demon 
 - filesystem handling. software raid handling. encryption of filesystems. 
-  time management. UCT times. NTP options
- conr options. cron administration.

You could offer a sample config which does all those examples. 


>  Also the editors included in the image are crap because they lack two important features: 1) keeping track of the damn paranteses and 2) comment and uncomment region. 

Yes. nano is crap. vi has paren matching, but doest keep tack of them . Editing lispy code with tracking of parens is not a pleasure. 

Also document every bug and quirk of this system.

 

> On Jun 20, 2018, at 07:46, swedebugia <swedebugia@riseup.net> wrote:
> 
> Hi
> 
> I would like to propose a rewrite of the README.
> 
> I'm wondering if it would be best to split it up in 2 files. 
> 
> One for guix and one for guixsd. 
> 
> 
> 
> Users come from other Distros where tough package manager errors mostly mean: you are screwed, reinstall. Because if you loose the central command to manipulate the system - how can you possibly recover? Imagine apt being corrupt or gone missing. 
> 
> So when we have strong reactions to users used to being screwed and reinstall then we need to educate them that this is something completely different where it is actually hard to break (besides when running guix pull and not understanding how to set paths manually) 
> 
> Another example:
> The current parsing of config.scm is eh... crude and might work for seasoned programmers who know the exact differences between parameters, instantiated config, where inherit works (record types) and where they don't (service-types), what a service object is, how you remove an item from a list of service objects, etc. 
> 
> I would like to tell new users NOT to change the config.scm at first install if they are not confident schemers. (besides the username and timezone perhaps). 
> 
> Also the editors included in the image are crap because they lack two important features: 1) keeping track of the damn paranteses and 2) comment and uncomment region. 
> 
> Edits to the configuration is in my view best done with small incremental steps in emacs and validating the config for each step (side note how do you validate your config from within emacs?). Access to irc to ask for questions/help when guix sometime spews incomprehensible errors at you is also advisable.
> 
> We also need a lot more complete examples of working snippets and whole config.scms to add to a config in the lack of good error reporting. 
> 
> Maybe a list of links to working configs from community members would be good to add Somewhere. I learned a lot from reading the
> Config of others. Perhaps in a new file called GUIXSD-CONFIGURATION-EXAMPLES? 
> 
> I saw that some of you, Alex, sidesteps the removal of service objects-problem by defining all the services yourself in a list instead. 
> 
> -- 
> Cheers Swedebugia

Re: Improving the README and new user experience

[Pierre Neidhardt]

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


I think this would be a great addition to Guix.

I agree that for now Guix' learning curve is pretty steep.  Even when
coming from rather barebone / Do-It-Yourself distributions like Gentoo /
Arch.

I'm not quite sure yet how to improve the experience to new users.  I'd
need to install it several times, with other people and for different
scenarios before I can be a better judge.

I know some work is being done to add an installation helper program to
the install image.

Dan Partelly <dan_partelly@rdsor.ro> writes:

>>  Also the editors included in the image are crap because they lack two important features: 1) keeping track of the damn paranteses and 2) comment and uncomment region.
>
> Yes. nano is crap. vi has paren matching, but doest keep tack of them . Editing lispy code with tracking of parens is not a pleasure.

Note that Guix also bundles Zile which is a tad better in my opinion.
Emacs would be Awesome but that would make the live image much heavier.

--
Pierre Neidhardt

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: Improving the README and new user experience

[Dan Partelly]

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

It is my oppinion that first you should very clearly define what you want from GuixSD 

a) is GuixSD to be a system which sees wide adoption , or is a system by developers for developers.
b) What kind of users ? Industrial use or amateurs at home ?
c) Server space, desktop space or both ?
d) if server space, actively think at security  and to the stability of the OS. Identify potential security risks of  running the custom kernel you have. Document it. Be open about it . Think at the implications of running a conservative garbage collector in several system demons. Uptime should be measured in year(s). See if it is a problem or not.Measure it .  Document it.
e) GuixSD is decent OS  and  follows NIX on the path of innovation . It would be a pitty to remain a niche used by a very small group of ppl . Do not focus just on the fact that the system is transactional, atomic and so on. Make it rock stable.


> I'm not quite sure yet how to improve the experience to new users.

1. Once you know this there is a lot you can do. Scheme is a good configuration language, but if you lack info on all the basics administration tasks and the semantics of the DSL the user is screwed. Documenting it is a must, for all common adminsitrative tasks
2. Make sure you use sound development practices, do not inflict the users upon the bleeding edge of your repository. I cannot stress enough how important this is, regardless of what you shoose to be the market of your product.
3. Treat it as a product, not as a hacking playground. I know it is not funny, but my guess is that it will help with adoption
4. Once you reach 1.0 , stop. Reflect on the bugs you have, and what documentation you lack. Make bug solving a priority for several point releases over new features. Or do both if you have sufficient manpower.
e) AIX Smitty is a great rpogram for configuring the system. It generates scripts, which the admin can execute and bring the OS in the desired state. You can generate Scheme from a similar system configuration tool, indicate the user it should review it, then
execute system recofniguration with guix command. 

> On Jun 20, 2018, at 10:20, Pierre Neidhardt <ambrevar@gmail.com <mailto:ambrevar@gmail.com>> wrote:
> 
> I'm not quite sure yet how to improve the experience to new users.  I'd
> need to install it several times, with other people and for different
> scenarios before I can be a better judge.



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

Re: Improving the README and new user experience

[Dan Partelly]

> I'm not quite sure yet how to improve the experience to new users.  I'd
> need to install it several times, with other people and for different
> scenarios before I can be a better judge.


Hi guys, 

Look, I started to watch more things on GuixSD , such as “Composing system services in guixSD or how we came….”  by Ludovic Courtes . I believe you guys should put in Guix manual some explication of concepts and some of the examples Ludovic does there,
that video helped a lot with GuixSD in general. 

Re: Improving the README and new user experience

[Danny Milosavljevic]

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

>>  Also the editors included in the image are crap because they lack two important features: 1) keeping track of the damn paranteses and 2) comment and uncomment region.   
>Yes. nano is crap. vi has paren matching, but doest keep tack of them . Editing lispy code with tracking of parens is not a pleasure. 

Nano has paren matching (Alt-]) and commenting out (Alt-3).  It allows you to select text with cursor keys, then shift-cursor keys.

It might make sense to patch the nano status line to mention that, though.

I agree that otherwise it leaves something to be desired - but it can be used for editing lisp source code just fine.

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

Re: Improving the README and new user experience

[swedebugia]

On June 20, 2018 10:24:47 AM GMT+02:00, Danny Milosavljevic <dannym@scratchpost.org> wrote:

... Snip

>Nano has paren matching (Alt-]) and commenting out (Alt-3).  It allows
>you to select text with cursor keys, then shift-cursor keys.
>
>It might make sense to patch the nano status line to mention that,
>though.
>
>I agree that otherwise it leaves something to be desired - but it can
>be used for editing lisp source code just fine.

That was news to me. Sounds good with a clarifying patch. 
Maybe the commenting out is just e making big changes and is is not needed for small incremental initial changes to the config. 
I will try to look into nano and see if I can figure out how to patch it. 

I think the manual should guide new users to a s little painful experience as possible. I will try building the installer and test it out as this would potentially take us a big step forward. 
-- 
Cheers Swedebugia