Improving the new user experience - Revision history

141.142.42.12: /* Obstacles faced by new users */

2017-09-05T14:47:01Z

‎Obstacles faced by new users

141.142.42.12: /* Obstacles faced by new users */

2017-09-05T14:40:57Z

‎Obstacles faced by new users

141.142.42.12: add comments

2017-09-05T14:40:04Z

add comments

Hinder at 19:06, 4 August 2017

2017-08-04T19:06:01Z

Hinder at 18:44, 4 August 2017

2017-08-04T18:44:39Z

72.36.113.38 at 18:36, 4 August 2017

2017-08-04T18:36:44Z

Hinder: /* New tutorial scheme */

2017-08-04T02:12:39Z

‎New tutorial scheme

Hinder: /* New tutorial scheme */

2017-08-04T02:11:47Z

‎New tutorial scheme

Hinder at 02:06, 4 August 2017

2017-08-04T02:06:10Z

Hinder at 22:50, 3 August 2017

2017-08-03T22:50:44Z

@@ Line 17: / Line 17: @@
 * Configuring the ET on a new machine is very difficult (even just compiling, let along interactions with queuing systems etc)
 ** It's particularly frustrating to me (Ian) that simfactory cannot figure out even simple things about a new machine (e.g. ppn), and if you don't get this right you aren't allowed to run multi-threaded jobs, etc.
 *** We have a patch (https://trac.einsteintoolkit.org/ticket/2059) from Mikael Sahrling which detects the number of cores.  Let's commit this during the workshop.
 *** Steve is working on automatically detecting the OS to choose the optionlist, and also something to do with which packages need to be installed (https://bitbucket.org/simfactory/simfactory2/branch/os_detect).

@@ Line 44: / Line 44: @@
 *** [RH] Formaline is likely not the culprit for the linking stage, it does not contribute much (couple 10MB), the major size factor is actually the debug information from "-g".
 ** Don't build MPI without warning the user.  Maybe abort and give the command or instructions to build it.
-*** [RH] that is already implements, the option is usually called "NO_BUILD" and just needs to be added to the option lists
+*** [RH] that is already implemented, the option is usually called "NO_BUILD" and just needs to be added to the option lists
 * Easy-ish on a new machine, but hard on a machine which already has a lot of packages installed, as they may be conflicting
 * The ET has a lot of dependencies, or compiles a lot of libraries (which sometimes don't compile successfully)

@@ Line 37: / Line 37: @@
 ** Maybe have multiple thornlists
 ** Maybe add tags to thorns, so that you can build just one type of thorn (e.g. those for BBH, or for NS, or something like that)
 ** Parallel build by default
 ** Linking stage very slow - Roland has some ideas
 ** Formaline seems to always be a suspect
 ** Don't build MPI without warning the user.  Maybe abort and give the command or instructions to build it.
 * Easy-ish on a new machine, but hard on a machine which already has a lot of packages installed, as they may be conflicting
 * The ET has a lot of dependencies, or compiles a lot of libraries (which sometimes don't compile successfully)
 ** Is the self-built version of OpenMPI ever actually usable?
 ** Erik has talked about using Spack for libraries.  Maybe we should push for this.  Erik now prefers "nix".
 * Many of the examples do not work
 ** Test automatically
@@ Line 51: / Line 57: @@
 ** At a previous workshop, this was evaluated, but there was no resolution ([[Fixing examples]])
 * On slower laptops, the build stage regularly hangs and has to be killed and restarted (which almost always solves the problem). Can we figure out which components are responsible, and omit them from quick-start tutorials?
-** RH: if the slower laptop also has less memory (or is a VM) then I would first try and monitor how much memory in particular the linker consumes. Testing this on my workstation it uses 1-2GB of RAM for a full ET build. On a 32bit VM with a cut down thornlist (no Formaline) it uses ~700MB. Similarly some C++ code takes a hug e amount of memory to compile.
+** [RH] if the slower laptop also has less memory (or is a VM) then I would first try and monitor how much memory in particular the linker consumes. Testing this on my workstation it uses 1-2GB of RAM for a full ET build. On a 32bit VM with a cut down thornlist (no Formaline) it uses ~700MB. Similarly some C++ code takes a hug e amount of memory to compile.
 * Comments: Some of the documentation (tex) files that come with thorns are blank. If I need more information about how to use a thorn with missing documentation, I usually look in the ccl files for clues. It would be nice to have any additional information from the ccl files in the tex files as well. (Lump all the details about a thorn in the same place.)
 * The mailing list and one or two calls I've joined so far were a huge help. But sometimes asking "beginner questions" over public channels makes me feel as if I'm wasting people's time. Up-to-date documentation with lots of details about parameters would be amazing! (Also, of course, time-consuming to write!)
@@ Line 58: / Line 64: @@
 * Important for examples to be able to run on laptops
 * Jupyter notebooks as an alternative (replacement?) to tutorials
 * Automatically-tested tutorials?
 * Missing tutorials/documentation, e.g.
@@ Line 66: / Line 73: @@
 * Have some more advanced tutorials
 * Simplified tutorial is hard to read  - big block for prerequisites
 * Queen Bee thing is hard to maintain - Steve wants to switch away from this
 * ET thorn documentation doesn't work in Chrome - see e.g. ADMAnalysis.  Need to fix tex4ht?  Or switch to another system for the documentation.
 ** Either switch to using something else (markdown?) for docs?
 ** or make the PDFs available
 * Demos: Jupyter example didn't work with Safari
 * List pointers/tutorials/documentation for things that pretty much everyone is going to need to know, especially for advanced features.
 * Subversion checkout even with homebrew on OSX doesn't work due to lack of certificates
 * curl, git, svn are not installed on a default ubuntu, so the first line of the tutorial doesn't work
 * The OS-specific optionlists should have the exact command(s) needed to install the packages, not split unnecessarily into several parts with text that needs to be read

@@ Line 74: / Line 74: @@
 * Subversion checkout even with homebrew on OSX doesn't work due to lack of certificates
 * curl, git, svn are not installed on a default ubuntu, so the first line of the tutorial doesn't work
+* The OS-specific optionlists should have the exact command(s) needed to install the packages, not split unnecessarily into several parts with text that needs to be read
 == New tutorial scheme ==

@@ Line 73: / Line 73: @@
 * List pointers/tutorials/documentation for things that pretty much everyone is going to need to know, especially for advanced features.
 * Subversion checkout even with homebrew on OSX doesn't work due to lack of certificates
-* curl is not installed on a default ubuntu, so the first line of the tutorial doesn't work
+* curl, git, svn are not installed on a default ubuntu, so the first line of the tutorial doesn't work

@@ Line 78: / Line 78: @@
 == New tutorial scheme ==
-We should have ''documentation'' which can be used as a complete reference for how things work.  We should also have "tutorials" which are instructions which can be followed step-by-step to achieve a certain goal.  We should not mix the two.  The thing that new users first want to do is to set up the Einstein Toolkit so that they can run it.  Let's write a "Setup tutorial" for this purpose.  This will include downloading, configuring, compiling, etc.  Then we can have additional tutorials for accomplishing other tasks.
+We should have ''documentation'' which can be used as a complete reference for how things work.  We should also have "tutorials" which are instructions which can be followed step-by-step to achieve a certain goal.  We should not mix the two.  The thing that new users first want to do is to set up the Einstein Toolkit so that they can run it.  Let's write a "Setup tutorial" for this purpose.  This will include downloading, configuring, compiling, etc.  Ideally, this should apply to any machine.  Then we can have additional tutorials for accomplishing other tasks.
 Tutorials:
-* Prerequisites, download, configure, compile
+* [[Setup Tutorial]] - Prerequisites, download, configure, compile
 * Test simulation - Hello World thorn (need to write it)
 * More advanced examples

←Older revision		Revision as of 02:11, 4 August 2017
Line 77:		Line 77:

	== New tutorial scheme ==		== New tutorial scheme ==
		+
		+	We should have ''documentation'' which can be used as a complete reference for how things work. We should also have "tutorials" which are instructions which can be followed step-by-step to achieve a certain goal. We should not mix the two. The thing that new users first want to do is to set up the Einstein Toolkit so that they can run it. Let's write a "Setup tutorial" for this purpose. This will include downloading, configuring, compiling, etc. Then we can have additional tutorials for accomplishing other tasks.

	Tutorials:		Tutorials:

←Older revision		Revision as of 02:06, 4 August 2017
Line 76:		Line 76:


−	==New tutorial scheme	+	== New tutorial scheme ==

	Tutorials:		Tutorials: