Sketch of analysis plan

Author: matthew-brett

analysis_plan.md

@@ -0,0 +1,79 @@
+# Analysis plan
+
+This is a sketch for your *analysis plan*, along with some instructions.
+
+Feel free to edit anything here. You may well want to digitally burn the
+instructions here after reading, to make space for your own thoughts.
+
+First, we should say that the term *analysis plan* is a big grand for what we
+are asking for here.  We wanted to use this week for:
+
+1. Practice on some Git / Github collaboration *with us and with each other*.
+2. Practice on editing [Markdown text](https://www.markdowntutorial.com).
+3. Giving you a chance to ask us questions about the project.
+4. Making sure you're ready to get going with improving your code to detect
+   outliers.
+5. Making a sketch of what you want to do over the next week or two for the
+   project.
+
+## Github practice, questions
+
+You are going to get this file (`analysis_plan.md`) as a *pull request*
+(PR) to your repository.
+
+Your first job is to use this pull request to ask questions of us, your
+instructors.
+
+What we propose you do, is use the pull-request (PR) interface to ask for
+clarification about the task, or the project.  You can enter comments in the
+PR interface, or go the "Files changed" tabs, and click on individual lines to
+add comments or questions about specific lines in the file.
+
+Once you are happy you've understood the task, merge this PR.
+
+## On Markdown
+
+The file is in Markdown format.
+
+Markdown is a *markup language*.  A Markdown file is a conventional text file
+that you can open in any text editor.  The special aspect of a Markdown file is
+the *markup*.   Markup consists of special bits of text that specify
+*formatting* of the text.  For example, in order to make a word in **bold**
+text, using Markdown markup, you put two asterisks either side of the text you
+want to be in bold.  When you want a properly formatted version of your
+Markdown file, you convert it to the formatted version, using a *Markdown
+renderer*.  A Markdown renderer is some system that can interpret the Markdown
+markup and display the text as you intended, with bold text as bold, headings
+as headings and so on.
+
+There are very many Markdown renderers, but the Github site is one.   When you
+put a `.md` file into your repository, like this one, and then navigate to the
+relevant file in the Github web interface, you will see that Github has
+*rendered* the Markdown formatting, showing bold as **bold**, headings as
+headings, and so on.
+
+Markdown has become the standard way of writing text files with markup, and you
+will see it everywhere on systems that programmers use, such as Github, and in
+the Jupyter notebook.
+
+Markdown has many dialects, meaning that there is some markup that every
+Markdown renderer understands, such as **bold**, and other markup that only
+some renderers understand.  The Markdown that every renderer understands is
+called [standard Markdown](https://www.markdownguide.org/basic-syntax). Github
+has its own dialect of Markdown, called [Github flavored
+Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github).
+You can usually stick to the standard stuff, but you may need to consult the
+Github documents if you want to do something slightly more fancy, like a table.
+
+## Making sure you're ready
+
+To be ready to get going on your project you need to make sure you have merged these three PRs:
+
+* "add-dvars"
+* "Add machinery to install module directory."
+* "Fix use of Path in find_outliers script"
+
+Make sure you've done the exercises there.  Run the following checks, from the
+homeworks:
+
+```