From 62123111a3480fb733e84a69695ce85871db4c28 Mon Sep 17 00:00:00 2001
From: Leandro Martinez <lmartine@unicamp.br>
Date: Tue, 18 Apr 2023 15:12:11 -0300
Subject: [PATCH] added docs on recommended workflow

---
 docs/src/installation.md | 60 ++++++++++++++++++++++++++++------------
 docs/src/quickguide.md   |  5 ++++
 2 files changed, 47 insertions(+), 18 deletions(-)

diff --git a/docs/src/installation.md b/docs/src/installation.md
index 1e31bccd..b8f40129 100644
--- a/docs/src/installation.md
+++ b/docs/src/installation.md
@@ -1,7 +1,9 @@
 # Installation
 
+## Install Julia
+
 First you need to install the Julia language in your platform, from: 
-[http://julialang.org](http://julialang.org). Julia version 1.6 or greater is required.
+[http://julialang.org](http://julialang.org). Julia version 1.6 or greater is required. Using the [juliaup](https://github.com/JuliaLang/juliaup) tool is also a highly recommended way of installing and keeping Julia up to date.
 
 !!! tip
      New to Julia? Julia is a modern high-level yet performant programming language. Some tips
@@ -9,36 +11,58 @@ First you need to install the Julia language in your platform, from:
 
      For this specific package, following a the step-by-step examples provided here after installing Julia should be enough. 
 
-Next, run julia, and within the julia REPL interface, install the ComplexMixtures package using
+## Install the packages
+
+Within Julia, to install the packages required for running the examples here you need to do:
+
 ```julia-repl
 julia> import Pkg
 
-julia> Pkg.add("ComplexMixtures")
+julia> Pkg.add(["ComplexMixtures","Plots","PDBTools"])
+```
+
+Please read the recommended workflow below, for further information and to be sure to have a smoother experience.
+
+## Recommended workflow for reproducibility
+
+### Create an environment
+
+Once Julia is installed, we recommend to create an environment that will contain all the packages you may use for your
+analyses, including `ComplexMixtures`, in such a way that your results can always be reproduced and you don't get
+any version incompatibility.
+
+We illustrate this by creating the "MyNewPaper" environment, which will be hosted in a simple directory,
+```bash
+mkdir /home/user/Documents/MyNewPaper
 ```
-or simply (you cannot copy/paste this, the `]` will take you to the `pkg>` prompt):
+
+Then, start Julia and activate the environment that will be hosted there:
 ```julia-repl
-julia> ] add ComplexMixtures
+julia> import Pkg; Pkg.activate("/home/user/Documents/MyNewPaper")
+  Activating new project at `~/Documents/MyNewPaper`
 ```
 
-To follow all the examples provided in this manual, the 
-[PDBTools](http://m3g.iqm.unicamp.br/PDBTools) 
-and [Plots](http://docs.juliaplots.org/latest/) have to be installed as well:
+and add to this environment the packages that your analyses will require:
+
 ```julia-repl
-julia> ] add PDBTools, Plots
+julia> Pkg.add(["ComplexMixtures","PDBTools","Plots"])
 ```
 
-If you are first-time `julia` user, load these packages for the first
-time after installation. Loading the `Plots` package, in particular, may
-take quite a while when done for the first time, because it is compiled
-at this point (this was greatly improved in Julia versions greater than 1.6, which
-are highly recommended). To load the packages, use:
+That's it. Close Julia. Note that this created the files `Manifest.toml` and `Project.toml` in the `MyNewPaper` directory, which contain the information of packages and exact package versions you are using now on in this environment. Saving these files may be relevant for the future exact reproduction of your analyses. 
+
+### Run your analysis scripts in that environment
+
+Now, your analysis scripts, described in the next section in details, will look like: 
 
 ```julia
-using ComplexMixtures, PDBTools, Plots
-```
+import Pkg; Pkg.activate("/home/user/Documents/MyNewPaper")
 
-If no errors were shown in any of these steps, the packages are ready to
-be used following the instructions and examples.
+using ComplexMixtures
+using PDBTools
+using Plots
+
+# etc ... 
+```
 
 !!! tip
     By loading the package with 
diff --git a/docs/src/quickguide.md b/docs/src/quickguide.md
index e923c587..ef1f2454 100644
--- a/docs/src/quickguide.md
+++ b/docs/src/quickguide.md
@@ -14,6 +14,9 @@ format in this example, which is the default output of `NAMD` and `CHARMM` simul
 packages.
 
 ```julia
+# Activate environment (see the Installation -> Recommended Workflow manual section)
+import Pkg; Pkg.activate("/home/user/MyNewPaper")
+
 # Load packages
 using PDBTools
 using ComplexMixtures 
@@ -71,6 +74,8 @@ where `-t auto` will launch `julia` with multi-threading. It is highly recommend
     ```
     The first time the script was called it took ~30s, which included compilation of the code and loading of the packages. The second time the script was included it took 0.7s. Thus, for interactive modification of the script, don't restart Julia.
 
+    This has been much improved in Julia 1.9, particularly if a stable environment is used, as suggested.
+
 ## Detailed description of the example
 
 Start `julia` and load the ComplexMixtures package, using: