Re: Improving the README and new user experience

[Dan Partelly <dan_partelly@rdsor.ro>]

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