From mboxrd@z Thu Jan 1 00:00:00 1970 From: Dan Partelly Subject: Re: Improving the README and new user experience Date: Wed, 20 Jun 2018 09:13:18 +0300 Message-ID: <7320F0B8-73A2-4E35-ADDE-D5E0E1E7E69A@rdsor.ro> References: <2BB0BF83-FB79-4D6D-AE22-9E8D6B095C75@riseup.net> Mime-Version: 1.0 (Mac OS X Mail 11.3 \(3445.6.18\)) Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:40023) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fVWMu-00020E-3A for guix-devel@gnu.org; Wed, 20 Jun 2018 02:13:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fVWMq-0003gb-U6 for guix-devel@gnu.org; Wed, 20 Jun 2018 02:13:24 -0400 Received: from imap.rdsor.ro ([193.231.238.8]:44792 helo=mail.rdsor.ro) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fVWMq-0003gB-HY for guix-devel@gnu.org; Wed, 20 Jun 2018 02:13:20 -0400 In-Reply-To: <2BB0BF83-FB79-4D6D-AE22-9E8D6B095C75@riseup.net> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: swedebugia Cc: Guix-devel 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=E2=80=99s 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)=20 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.=20 - 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 =E2=80=A6 0.14.n, branches which where regression tested = before beeing inflicted upon the user.=20 > 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.=20 This is not true. In classical distros, the central command to recover = is not the package manager per se. It=E2=80=99s 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.=20 > 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)=20 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).=20 I dont think it=E2=80=99s 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=20 - boot and initrd handling. Add new drenel driver to kmod Options for = init demon=20 - filesystem handling. software raid handling. encryption of = filesystems.=20 - time management. UCT times. NTP options - conr options. cron administration. You could offer a sample config which does all those examples.=20 > 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.=20 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.=20 Also document every bug and quirk of this system. =20 > On Jun 20, 2018, at 07:46, swedebugia wrote: >=20 > Hi >=20 > I would like to propose a rewrite of the README. >=20 > I'm wondering if it would be best to split it up in 2 files.=20 >=20 > One for guix and one for guixsd.=20 >=20 >=20 >=20 > 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.=20 >=20 > 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)=20 >=20 > 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.=20 >=20 > 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).=20 >=20 > 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.=20 >=20 > 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. >=20 > 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.=20 >=20 > 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?=20 >=20 > I saw that some of you, Alex, sidesteps the removal of service = objects-problem by defining all the services yourself in a list instead.=20= >=20 > --=20 > Cheers Swedebugia