Merge pull request #329 from mmesiti/fix-intro-spring2026

Minimal fix of intro for 2026

Author: frankier

CITATION.cff

@@ -26,6 +26,8 @@ authors:
   given-names: "Kjartan Thor"
 - family-names: "Wittke"
   given-names: "Samantha"
+- family-names: "Mesiti"
+  given-names: "Michele"
 title: "How to document your research software"
 type: "dataset"
 abstract: "The lesson 'How to document your research software' gives an overview of the different ways how a code project can be documented: from small projects to larger projects. Markdown and Sphinx are central tools in this lesson."

content/index.md

@@ -3,19 +3,22 @@
 In this lesson we will discuss different solutions for implementing and
 deploying code documentation.
 
-We will start with a discussion about **what makes a good README**. For many
-projects, a README is more than enough.
+This demonstration will be mostly **independent of programming languages**
+(you will be able to follow and do all the exercises
+using the [CodeRefinery conda environment](https://coderefinery.github.io/installation/conda-environment/)).
 
-We will then learn how to build documentation with the
-**documentation generator** [Sphinx](https://www.sphinx-doc.org) (and compare it
-with others) and how to
-deploy it to [Read the Docs](https://readthedocs.org), a service which hosts
-open documentation for free.
 
-This demonstration will be **independent of programming languages**.
+We will discuss best practices, and briefly discuss the available tools.
+
+Then we will discuss the form of documentation which is the most immediate to write:
+**in-code** comments, and docstrings.
+
+We will step up our game and discuss **what makes a good README**. For many
+projects, a curated README is enough.
 
-We will also learn how
-to deploy a **project website or personal homepage** to [GitHub Pages](https://pages.github.com).
+We will then learn how to build documentation with the
+**documentation generator** [Sphinx](https://www.sphinx-doc.org) and how to
+deploy it to [GitHub Pages](https://pages.github.com).
 The approach that we will learn will be transferable to
 [GitLab Pages](https://about.gitlab.com/features/pages/) and
 [Bitbucket Pages](https://pages.bitbucket.io).
@@ -33,6 +36,11 @@ If you wish to follow in the terminal and are new to the command line, we
 recorded a [short shell crash course](https://youtu.be/xbTTDLA3txI).
 ```
 
+An optional episode is about 
+deploying a **project website or personal homepage** 
+to [GitHub Pages](https://pages.github.com).
+
+
 ```{csv-table}
 :widths: auto
 :delim: ;