This is a thread for critiquing the notebook Introducing Functions. It is under notebooks/introducing_functions.

As we move into focusing on projects, there will be more notes about OS-specific implementations. It would be good to have these collapsible, so readers only see notes specific to their OS.

When people have to fight their OS to do something, it is good to point out in that OS' section that it is easier on other systems. Encourage new people developing on Windows to consider trying Linux. Not evangelism; just objective "This is how you do it on Linux, which is easier for this reason. You might want to give it a try." Follow that with a link to an expanded section in the programming_environment notebook about trying Linux on a vm, or a dual boot, or an extra computer.

As I have written different sections over the last few months, I have bounced around between the pronouns I, we, and you. This probably reads inconsistently for anyone who works through the notebooks from hello_world through the projects.

As more people start to contribute to the project, I am guessing that "we" is a good approach.

So, I think the following needs to be done:

• Agree that "we" is better than "I" in most cases.
• Read through the site's copy, from hello_world through to the projects, and edit for a consistent tone in this regard.

Now that the project uses matplotlib, and two virtualenvs with two different versions of Python, the setup process can easily fail to complete. There are many dependencies between these packages, and I haven't even brought Basemap into the readme yet.

I have been destroying and building virtualenvs repeatedly, but it would be good to run through the process described in the readme on a vanilla Ubuntu 12.04 vm, and make sure I haven't left out any system-wide requirements.

I would also love to see a version of these setup instructions for non-Ubuntu systems.

This information is pretty dense for new programmers. The fun part is learning a little bit, and then doing some exercises or trying some challenges. Rather than sprinkle exercises after every little section, encourage people to read a bit and then look at the exercises sections, doing the ones they can.

Basic workflow:

• Write a skeleton notebook for an upcoming lesson.
• Add any missing examples/ clarifications while presenting to students
• Commit changes and push live, in front of students, at end of lesson
• Later, clean up and add links and navigation, further clarifications, etc.

This workflow is meant to also show students how collaborative tools such as github work.

From #29:

The total size of css files included at this point is almost 500kb. On modern systems this should be trivial, especially once resources are cached. But a simple improvement would be to scrape the built pages, and remove any elements from the raw style definitions that are not actually used in html pages.

My rough guess, for the record, is that this step would result in an overall css cumulative file size of 10% of the non-optimized total. There is so much functionality in ipython's css, and bootstrap's css, that the majority of it is unused.

Not a high priority right now, but if the site sees more use this is worth keeping in mind. If you want to see the individual files, take a look at the source for a typical deployed page.

As the notebooks gain more detail, I wonder if it might be useful to allow hiding of notes that refer to Python 2. They need to be in there, but it would be good to aim for the simplest, cleanest page possible for learners, without omitting needed details.

(Watching the Python 2/ Python 3 transition difficulties is not fun atm.)

The navigation bar is getting crowded:

I added the "Home" element because I couldn't figure out how to make the project name "Introduction to Python" link to the index page. If this can be fixed, we can probably get rid of the "Home" link. Before getting rid of this, we should make sure the new navigation works on mobile.

I'm also not sure about the social media buttons. I'm not sure we need all three there.

The Visualizing Global Earthquake Activity has always been well-received. Someone recently requested an extension of this project that would show how to deal with more dimensions of data:

What about displaying 3D data. Any examples? For example, showing roads with the third dimension representing the traffic load on the road or the number of potholes/deaths/accidents per mile.

I would love to get to this at some point, but I probably won't dig into it for a while. This would be a great project for someone to write up.

Two pages have the "next"-Page link only at the top but not at the bottom.

http://introtopython.org/introducing_functions.html
http://introtopython.org/lists_tuples.html

The other pages are okay.

Main resources to include:

• Resources for independent learning
  • udacity, codecademy, coursera, edx, lpthw
• Exercise/ Challenge resources
  • codingbat, project euler

This will have a number of benefits:

• It is a much simpler hosting infrastructure.
• Pages should load faster. This is mostly an issue with longer notebooks, which should be broken into smaller notebooks anyway.
• Can add tracking metrics such as Google Analytics.

Exercises

• provide opportunity to practice what was just presented, and only what was just presented
• make it easy for students to focus on what was just presented, by depending on as little other skills and knowledge as possible

Challenges

• go beyond the minimum understanding of what was just presented
• have students integrate prior skills and knowlege

Examples of sections with a good mix of exercises and challenges:

• Numbers - Exercises and Challenges

I am using the different heading levels inconsistently. This could be cleaned up by clarifying the levels within each notebook.

Something like this is ideal:

Main Topic

Major Subtopic

Subtopic detail

Even finer detail

I have long thought that one of the biggest strengths of introtopython.org is the ability for strong programmers to improve the site as they look it over. Once it reaches a critical mass, introtopython.org should stay pretty up-to-date and relevant because anyone can catch a mistake, or something out of date, and submit a PR to fix it.

One significant way to grow the project would be to recruit people with expertise in different areas of Python to write notebooks that feature different projects. There could be a whole series of mapping projects, data visualization projects, game projects...

Rather than me or a few people trying to write up a bunch of projects that are not really in our area of expertise, we should try to find the right people to write a series of projects. I think I might reach out to the matpotlib/ data viz community and see if anyone is interested in writing up a project.

In the meantime, if anyone has a specific project to request, let's ticket it and use the Project Request label.

Functions:

• scope
• passing mutable arguments such as lists

I don't think there will be a whole lot of tests for this project, because it's mostly a writing project. I don't envision all of the code in the notebooks being tested; a good error reporting system should take care of those issues.

test_links.py

One test I do care about is the ability to test all links in the project. Links are particularly important for this project, because every time someone follows a link, they are trying to understand something. Broken links make it difficult to build understanding, which would quickly lead to frustration. People also use links to navigate to the topics they are currently working on, and to go back to topics they are starting to understand but need some review on.

This test should:

• verify that all links between notebooks are working;
• verify that all external links are working;
• verify that all anchor links are working.

The test currently finds all links in a local cache of html files. It then tests those links against either a locally served version of the project, or an externally deployed version. The --root (-r) flag lets you set the url root that the files are served at, which is by default http://localhost:8000, the address of the SimpleHTTPServer that is run by the script itself. The test should either find links from local html files, and then test those locally, or find links from deployed files, and then test those deployed files.

For now, I can use the script as is to test locally (that will continue to work), or I can deploy and then test the deployed files. It's a bit scrappy for the moment, but it works for now and refinement of this script is fairly low-hanging fruit.

The readme is pretty sparse right now, so if you are trying to get involved and have any questions about setup, please feel free to ask them here.

Individual lines of code can now be highlighted in code cells, once converted to html. This feature will improve the following notebooks:

• (finished 12/6) while_input
• (finished 12/7) dictionaries
• (finished 12/8) more_functions
• (finished 12/8) var_string_num
• (finished 12/9) lists_tuples
• (finished 12/11) introducing_functions
• if_statements

I have my overall system to run python2.7 or python3.3. I have not configured a virtualenv to do this yet.

The readme should be updated with this information.

Makes it much easier to talk about with students and others. Also makes it easier to track which exercises have been completed.

There are many collections of Python exercises, and programming exercises in general online. But many of those very quickly get into intermediate-level problems. The problem set that introtopython.org contains could be very appealing to brand-new programmers, who cannot progress quickly enough to keep up with many existing sets of exercises.

The goal of this work is to pull out all exercises and challenges into one place, so that people can choose to try these exercises and challenges without having to skim through all the explanatory text. With a proper presentation, people who get stuck on certain exercises would then be likely to go to the relevant sections of the overall project to learn what they need to in order to complete the exercises. It could be a really good teaching and learning resource, and a good PR piece as well.

I am actively working on this on the branch all_exercise_page. I won't link to the page from the main project until it is complete and presented well, but the evolving page will be at introtopython.org/all_exercises_challenges.html.

I'm not expecting any particular help at this point, but with a few more eyes on the project I'm going to be more clear about my current focus. After landing this, I will probably go back to focusing on having enough content to bring people all the way from hello_world to the projects. Then it will be a fun job of writing up a few projects, and asking some new programmers to try the site out and share feedback. Long-term, there's some fun outreach we can do to teachers who don't come from a CS background, but who want to introduce their students to programming.

I wouldn't call it a "Issue". I would prefer the term "Wish".

I wish there was a easy way to add translations to intro_programming. But I couldn't find a way to add translations to IPython notebooks.

I'd be willing to make an attempt for a translation to german, but I feel that without support from the library side this will fail as soon as there are updates from the original english course.

There should be enough exercises that students can get help on a number of exercises, and then still have enough to complete a number of exercises independently. If students don't get to the point of writing simple programs independently, they will not get far in programming.

This can easily clutter up the notebooks. I have several thoughts about managing this:

• Make the exercises collapsible. When the notebook loads, exercises are hidden. When a student is ready to do the exercises, they click a show exercises button, and they can see the exercises.
• Include 2-3 exercises in each teaching notebook, and then link to a separate notebook with more exercises.

I like Bootstrap sites, and I think it would add something to the project as it stands. We could leave bootstrap at some point, but it would make the styling better than what we see from a simple nbconvert.

This is a thread for critiquing the notebook Lists and Tuples. It is under notebooks/lists_tuples.

There are a number of ways to optimize the html, for better load times and better user experience.

• Pull css into a separate file. It seems the command ipython nbconvert dumps all css for all possible notebooks into the head of each html file. This makes sense, because many notebooks are meant to be standalone pieces. For this project, it makes sense to pull the css into a separate file. I believe user's browsers are not caching css, since it is included in each page.
  • This has been done.
• Use bootstrap? The basic appearance is not that bad, but if the focus is on creating a website, there are some improvements that bootstrap can help with.
• Consider using ipython nbconvert --template basic. This would require generating our own css, but that might work better. I am guessing there is a lot of css that we are not using. It might be reasonable to write our own css rules or create our own template for a basic Introduction to Python site.
  • This has been done.
• Test all internal links. Write a test that goes through each notebook, verifying that each internal link is working correctly.
  • test_links.py currently tests links between notebooks and external links, but no anchor tags. The script can easily be extended to cover anchor tags.
• Test all external links. This is a much more resource-intensive test, but it could be really useful as the project moves forward. There are not many external links at this point, but it would be really good to link to docs.python.org as the project matures. There are plenty of other good external resources that we should share with teachers and students. Finding broken links before link rot sets in would go a long way towards maintaining a clean user experience. Issue 8 | Issue 4
  • test_links.py currently tests links between notebooks, and external links. Tests locally, and I have used it to check deployed html pages. Can be cleaned up to take flag testing for local or deployed pages.

It was not clear to me when I started the project that this would be set up as a website. That is one of the primary goals of the project at this point, so this renaming simplifies deployment of html files.

@ehmatthes
I am wondering if you have considered an in-browser editor like Skulpt [1]. This will be useful for students to test code live.

I have attached a screenshot for the same. This is a crude hack. I included example code after generating html.

[1] http://www.skulpt.org/

My main focus is on the static html project at introtopython.org, but I still want the notebooks themselves to work together as a cohesive project, as viewed through Notebook Viewer.

I just updated the index.ipynb notebook to match the index.html page, but this should be checked periodically as the overall project continues to evolve.

build_html_pages.sh

I started this as a series of shell scripts, so that different sections of the pages could be managed separately. But as I look at the whole series, it probably makes sense to pull them into one file, or a smaller series.

May also rewrite the entire series in Python, this was just what I already knew how to do in bash. I will rethink that as I start to play with the html files more. As of right now they are just a mirror of what nbconvert produces.

Regardless, the script should continue to work either by itself, or run from a commit hook.

For "naming and defining a list" on List and Tuples, there is no number for the input, e.g. In[]:.

(very minor)

I have a series of custom scripts that build the html pages. Might be much more efficient to use an existing templating engine, rather than my own custom script.

Not a pressing problem, because the custom scripts are not that difficult to manage, and I'm not exactly sure what a larger templating engine would bring to the project at this point.

Templating engines to consider, and other relevant information:

• see this thread on ipython mailing list
• Nikola
• IPython make notebook index
• nbconvert source on github
  • nbconvert issues

Really should choose a Python static site generator:

• jinja, pelican, hyde, nikola

Please share any feedback on this notebook, particularly any suggestions on how to clarify or improve the installation and setup instructions.

This is a thread for critiquing the notebook Variables, Strings, and Numbers. It is under notebooks/var_string_num.

There should be enough exercises that students can get help on a number of exercises, and then still have enough to complete a number of exercises independently. If students don't get to the point of writing simple programs independently, they will not get far in programming.

This can easily clutter up the notebooks. I have several thoughts about managing this:

• Make the exercises collapsible. When the notebook loads, exercises are hidden. When a student is ready to do the exercises, they click a show exercises button, and they can see the exercises.
• Include 2-3 exercises in each teaching notebook, and then link to a separate notebook with more exercises.

I was browsing the site and noticed that on double-digit input history references were a bit closer to the execution than their single digit friends.

From var_string_num.html:

If you remove width: 11ex from nbconvert_styles.css.

This also ensures that if you have any longer-digit numbers, the padding will be correct still.

Currently you have to go back to the index page or the syllabus to get from one notebook to another. Make a "previous - index - next" style navigation at the top and bottom of each notebook.

I have no idea if this is necessary. Technically, I don't think it is. All of the content on the site is actually part of the repository, so I believe the MIT license covers everything.

Still, it would be good to verify whether a CC license is necessary or not.

Why write exercises?

One of the strengths of this project is that students can learn a new Python concept, and then apply what they've learned by trying to complete a short series of exercises. That makes high-quality exercises one of the most important parts of the project.

There should be enough exercises that students can get help on a number of exercises, and then still have enough to complete a number of exercises independently. If students don't get to the point of writing simple programs independently, they will not get far in programming.

This could be one of the most straightforward and helpful ways to contribute to the project. If you'd like to help write some exercises or challenges, please fork the project and make a pull request. If you're not sure how to do that, please feel free to ask, and I'll help you get through the first pull request.

Exercise or Challenge?

An exercise asks the learner to use what was just covered, in a way that mostly repeats the examples that were just given. The exercise can use a new context, but it should tell the learner to use a specific skill to complete a specific task.

A challenge asks the learner to combine what they have just learned with significant previous concepts. A challenge may be less directive and more open to interpretation; it may ask the learner to solve a problem that can be solved with a newly learned concept, without being overly directive about how to use the new concept.

Examples

The following notebooks have decent starter exercises for each main topic that is introduced:

• Variables, Strings, and Numbers
• Lists and Tuples
• Introducing Functions
• If Statements
• While Loops and Input
• Basic Terminal Apps

These are just some starter exercises, so please feel free to add more.

Notebooks with few exercises

The following notebooks have sections with no exercises yet:

• Dictionaries
• More Functions

I would love to have some help writing decent exercises for these notebooks.

Invitation

Writing exercises and challenges can be fun and satisfying. If you want to help but are not sure how to get started, please introduce yourself in this thread and I'll be happy to help you get started!

Python function names, such as my_list.append(item), are written right now in an informal way so as to not put off beginners in the text. So append is just referred to as "the append() function".

This seems good, but it does not show people the general format. Perhaps work in the general format as well, at some point in the discussion of each significant function.

Some of the notebooks, as currently laid out, are pretty long. This makes the project feel more like a reference than an active learning tool. Breaking into smaller sections would probably make it easier for students and teachers to navigate, and to feel like they are making progress.

What's an ideal chunk size?

• Keep the outer hierarchy roughly the same as it is currently laid out in the syllabus.
• Each major subject within the current notebooks should probably become its own notebook.
• All sections should end with Exercises, and challenges wherever appropriate.

If anyone is interested in helping out, here are a number of ways you can jump in:

Write more exercises.

• Ideally, we would have 3-5 exercises for each aspect of each major topic presented. This gives students the chance to do an exercise or two with help, and then complete another exercise or two independently. The goal is that students can solve at least one exercise in each section independently.

Write more challenges

• Exercises ask students to write a small program that demonstrates competence with one particular skill or concept. Challenges ask students to combine different skills, or use new skills to implement developmentally appropriate versions of their own ideas.
• Challenges can be written in any section, right after the Exercises for that section. It would also be good to develop a good set of interesting Challenges at the end of each notebook.

Write up a project

• Now that the Python essentials are mostly written, the interesting work is writing up projects that people will want to complete. Propose a project, and write a notebook that shows people how to complete the project.

Proofread for accuracy

• If you have a solid understanding of programming skills and concepts, I'd love to hear feedback about anything that could be explained more clearly, or more accurately.

@ehmatthes

For example, when the list.insert(i, item) is introduced, link to the official documentation for insert().

May be good to somehow distinguish between internal and external links.

It is really helpful to see the general syntax before getting into examples and details. If this is not shown, students have to infer the general syntax.

See Introducing Functions.

The scripts for converting from ipynb to html successfully depend on a specific formatting for Exercises and Challenges. In particular, the script that builds the all exercises and challenges page needs specific formatting.

This should probably be documented in the readme, or in a page linked to from readme. Research the conventions for supporting readme pages; more markdown pages, or make a wiki? I lean towards markdown, but not sure if that's conventional. I like markdown pages because they are part of the repo that gets cloned.

Exercise sections should follow this format:

• Make a new cell.
• Make a line with the label "Exercises", followed by ---
• Make a series of exercises, with titles preceded by ####
• Start a new cell, with a link to top

This is what the code in your notebook should look like:

<a name='exercises_section_identifier'></a>Exercises

---
#### Title of Exercise
- specific directive
    - more specific directive

#### <a name='exercise_title_of_exercise'></a>Title of Exercise
- specific directive
    - more specific directive

[new cell]
[top](#)

The script for all_exercises_challenges looks for the top cell when scraping for exercises and challenges.

Sets of Challenges follow the same format, with the word 'Challenges' in place of 'Exercises'.

Initially, notebooks are written with a table of contents, and then a series of text and code cells. Add links from table of contents to appropriate sections in the notebook.

If you have some general feedback about the project, feel free to leave it here.

The exercises are one of the strongest features of this project. Most problem sites are aimed at higher-level programmers. When this project is mature, there should be a good set of gradually-graded exercises and challenges that people completely new to programming can work through at their own pace. There should be enough redundancy that people can get help with three or four exercises, and still have three or four more to work through independently.

It is good to have the exercises listed in with the content. It encourages people to try their hand at exercises as they learn, rather than pretending they get something because they read it. It would be quite useful, however, to also have a page that only lists exercises. So, I am envisioning:

• an 'index' page for all exercises
• a tagging or categorizing system for exercises so that people can search by context of the exercise, and Python concepts that the exercises focus on.
• a feature that makes it easy for teachers to select and print exercises for students
• a feature that makes it easy for students to select and print their own series of exercises.