Dev tools review

prof-rossetti · Jan 6, 2025 · 3376a92 · 3376a92
1 parent 4596f81
commit 3376a92
Show file tree

Hide file tree

Showing 9 changed files with 45 additions and 21 deletions.
diff --git a/docs/images/colab-document-outline-expanded-selected.png b/docs/images/colab-document-outline-expanded-selected.png
diff --git a/docs/images/colab-document-outline-expanded.png b/docs/images/colab-document-outline-expanded.png
diff --git a/docs/images/colab-document-outline.png b/docs/images/colab-document-outline.png
diff --git a/docs/images/python-notebook-adoption-2024-with-title.png b/docs/images/python-notebook-adoption-2024-with-title.png
diff --git a/docs/images/python-notebook-adoption-2024.png b/docs/images/python-notebook-adoption-2024.png
diff --git a/docs/images/python-notebook-inputs-outputs.png b/docs/images/python-notebook-inputs-outputs.png
diff --git a/docs/notes/dev-tools/google-colab/overview.qmd b/docs/notes/dev-tools/google-colab/overview.qmd
@@ -13,7 +13,7 @@ When creating a new notebook, practice giving the document a title (e.g. \"My Fi
 
 From any notebook, it is possible to create a new notebook, make a copy of the notebook, or download the notebook, using the \"File\" menu.
 
-![Google Colab File menu](../../../images/colab-file-menu.png){.img-fluid style="max-height:350;"}
+![The File menu in Google Colab.](../../../images/colab-file-menu.png){height=350}
 
 
 ::: {.callout-warning}
@@ -35,7 +35,7 @@ Recommended editor settings:
   + **Enable code folding**: so you can focus on certain parts of the code, and make the code more manageable to navigate.
 
 
-![Recommended editor settings in Google Colab](../../../images/colab-settings.png){.img-fluid style="max-height:450;"}
+![Recommended editor settings in Google Colab](../../../images/colab-settings.png){height=350}
 
 Remember to save your preferences before moving on.
 

diff --git a/docs/notes/dev-tools/google-colab/table-of-contents.qmd b/docs/notes/dev-tools/google-colab/table-of-contents.qmd
@@ -6,48 +6,62 @@ The heading structure of your markdown cells will govern the document structure
 
 
 ```md
-# Section 1
+# Header 1
 
 This is some text.
 
-## Section 1.1
+## Header 2
 
 This is some text.
 
-## Section 1.2
+### Heading 3
 
 This is some text.
 
-### Section 1.2.1
+#### Heading 4
 
 This is some text.
+```
 
-### Section 1.2.2
+::: {.callout-tip title="Note"}
+You may need to place each of these headings in its own separate text cell, for the document outline to collapse properly.
 
-This is some text.
+![Document outline in Google Colab.](../../../images/colab-document-outline-expanded.png){height=350}
+:::
 
-# Section 2
 
-This is some text.
+<!--
 
-## Section 2.1
+```md
+# Header 1
+```
 
+```md
 This is some text.
+```
 
-## Section 2.2
+```md
+## Header 2
+```
 
+```md
 This is some text.
+```
 
-### Section 2.2.1
+```md
+### Heading 3
+```
 
+```md
 This is some text.
+```
 
-### Section 2.2.2
+```md
+#### Heading 4
+```
 
+```md
 This is some text.
-
 ```
 
-::: {.callout-tip title="Note"}
-You may need to place each of the headings in its own separate text cell, for the document outline to collapse properly.
-:::
+-->
diff --git a/docs/notes/dev-tools/index.qmd b/docs/notes/dev-tools/index.qmd
@@ -4,12 +4,22 @@ So you want to develop programs and applications in Python?
 
 You'll need to familiarize yourself with a Python development environment. One of the hardest parts of computer programming can be installing the language, and getting up and running with local development tools. But we will help guide you through the process, and recommend using tools that offer a low learning curve for beginners.
 
+In Python, we have a general choice between two development environments: Python notebooks vs local development, each offering its own strengths and trade-offs. Ultimately we recommend Google Colab notebooks for their accessibility and ease of use for beginners.
 
-## Notebooks vs Local Development
+## Python Notebooks
 
-In Python, we have a general choice between two development environments: Python notebooks vs local development, each offering its own strengths and trade-offs.
+Python notebooks (\".ipynb\" documents) provide an easy and intuitive learning experience for beginners. They have code \"cells\" we can "play" to see the results and learn along the way. The integration of visual outputs along with code provides strengths in terms of presentation.
 
-Python notebooks (\".ipynb\" documents) provide an easy and intuitive learning experience for beginners. They have code \"cells\" we can "play" to see the results and learn along the way. The integration of visual outputs along with code provides strengths in terms of presentation. Notebooks are also a popular choice among data science and machine learning practitioners, especially for quick prototypes, and rapid development. However for larger applications they might not be as suitable.
+![Python notebook with code input and dataviz output.](../../images/python-notebook-inputs-outputs.png){height=320}
+
+
+Notebooks are also a popular choice among data science and machine learning practitioners, especially for quick prototypes, and rapid development.
+
+![Rising popularity of Python notebooks. Source: [GitHub Octoverse 2024](https://github.blog/news-insights/octoverse/octoverse-2024).](../../images/python-notebook-adoption-2024.png){height=320}
+
+However for larger applications they might not be as suitable.
+
+## Local Development
 
 Local development environments are used primarily for software development purposes, and for larger-scale applications which may span across dozens of files. The local development environment involves command-line programming tools that can be tricky to install and configure for beginners. For some types of applications, such as web applications, local development may be the only suitable option.