v0.2.3 Progress Report

[Robert Holder]

We've gotten most of the fwcTools2 section (C01S06) done. We're working on the "Storing Data" section now, which will introduce arrays, pointers, typdefs, structs, vectors and maps. We hope to merge the development branch (where we make changes) into the master branch (the "stable" one people will download) soon.

We spent a lot of time looking at and discussing the table of contents of various C and C++ programming textbooks, and we've tried to come up with a sequence of introducing language elements and concepts of C++ that is oriented towards getting the user involved directly in coding right away, as opposed to having lots of exposition about how the language works, where the user is having this passive experience reading about coding, instead of jumping in and actually coding.

We've had a handful of people tell us they have downloaded the software and tried to play with it. So far, people seem to be getting stuck though, and have trouble getting started actually working on the exercises.

We think the problem is that people aren't getting the relationship that each exercise .cpp file runs in it's own little dropdown, and that the goal of every exercise is to make the left side of the runtime window look/behave like the right side. Our impression is that the people who've downloaded fwc and gotten it to build and run in the Qt SDK sort of get stuck, not knowing how to proceed, what they are supposed to do, or how to do it.

We think maybe a couple videos might help make this clearer. So we've started creating an introductory 3 minute video that explains the basic idea of what fwc is, and we're also talking about making another longer video, like maybe 8 minutes, that walks the user through how to get started working on the exercises with narrated video of how to use fwc in the Qt Creator IDE.

While our goal is to get people coding right away, and get their feet wet :), it is true that every beginner does have to sit down and read a C++ textbook or online tutorial. This problem where people don't seem to be able to get started has us a little concerned, and we are trying to figure out how to remove as many obstacles as we can that might be holding the user up.

We also wonder if maybe people are afraid to touch the code, and we want to get some sort of statement into the docs that tries to encourage the user to start changing code right away. For fwc to help people learn, they can't feel hesitant to change the exercise code. So far, we're not hearing, "I changed this exercise, and now the program won't compile", instead we hearing "I don't know how to get started" and we're trying to figure out how to make it clear to the user what the process of using the exercises actually is.

To start coding, you need this basic toolbox of seven concepts: variables, conditionals, loops, expressions, functions, I/O tools and "syntax" meaning the basic syntactical rules of the language.

That's the bare minimum, those seven things and then with C++ you also need to understand how to write and use classes. Storing data becomes more complicated as the beginner learns, but in the very beginning, just to start getting some simple programs working, and start to understand the edit > run > analyze > debug > edit loop that the activity of programming actually is, all they need to get started are those seven mental "tools."

We think maybe the problem is that the beginner doesn't have a clear idea of what these basic tools are, and how they fit together to make a program. We're talking about trying to have a diagram or video or something that will get across this idea that most of beginning programming boils down to these seven conceptual tools. When you look at the table of contents of a C++ book, it looks a lot more complicated and hard to absorb than this, and I think this may be how some people get overwhelmed in the beginning. It's easy to get lost in all the specific details of ints and doubles and floats and bools, and trying to absorb a bunch of new concepts at once, and not be able to step back and see the big picture, to see that most of what beginners learn up front will fit in one of those seven conceptual boxes.

The specific details of how a program works can become very complex and abstruse, but I think that many beginners will look at even a little ten line program, with all this strange text they've never seen before, and not be able to get a conceptual handle on what they are looking at, and I think this is where they may get tripped up. So if we can figure out how to help them get a handle on these seven basic anatomical parts of what most beginning programs are made of, maybe that will help.

Trying to see the code through the beginner's eyes is as challenging as actually writing fwc, at least for me! :) But I think it's necessary to try to do that. Learning to program is about knocking down cognitive obstacles, and seeing more clearly, and I really want to try to help the beginner do that. It's hard work, but it's fun! :) I sure hope somebody finds this dang project useful someday, lol! :) Sometimes I wonder.

Beginners also need to be able to decipher compiler errors, and we haven't explained how to get started learning that at all in the documentation. Again, we think a video or two might be helpful to get people to at least know where to look for those errors. In the Qt Creator IDE, build errors appear in one pane, and compiler errors and warning appear in another, and beginners will not have any idea where to look if they make a change to the exercise source and suddenly the whole program won't compile. We've got to do a better job at convincing the user to explore, experiment, click on stuff, play with the tools, and completely lose their fear that they might break anything. I wrote this essay for the docs exhorting the user to BREAK THY CODE and all this stuff to encourage them to get their hands dirty, get their feet wet, but I'm not ready to include it in the docs yet. I'm not sure where to put it, and it's not well-written yet.

The problem of how users are supposed to start learning how to interpret compiler errors is a big problem, we can't really automate that for them, and we're concerned about it, in terms of how we structure the learning process.
We have the idea that we will have a section of exercises with code that contains some common typos, syntax errors and so on. We will comment these out (if they aren't commented, the whole program won't build) and then explain to the user that they need to uncomment the offending line, and compile, and look at the compiler errors, so they can start to recognize which errors mean which kinds of problems in the code. It's pretty common in C++ for the compiler to puke on one line, where the real problem is on another line, and that idea is something we need to get across to the user.

So with this idea of including these kinds of "example error" exercises, we can at least demonstrate for the user what some common errors look like in terms of compiler errors. But when you think about all the possible types of errors beginning programmers are likely to make, it's pretty daunting thinking about how to give examples of everything. We're still thinking about this problem.

I (rdh) made changes to the documentation table of contents structure in helpndoc, and now that version of the toc doesn't display properly in chrome. This "what format do we use for documentation" problem has been an on-going headache. We're thinking we might just do it in google web hosting now though: google to the rescue again, yay! But it will be a lot of work to manually recreate all the docs by hand. sigh. Helpndoc would be awesome if it didn't have so many problems.

We liked helpndoc because it allowed us to include the whole html based documentation in the repo, (Helpndoc generates this nice static html structure that can live just as happily on the user's local filesystem as on a web server) so that when users clone or download the zip from github, they have all the docs right there on their harddrive, without having to have a persistent internet connection in order to look at documentation. But sheesh, everybody (in the first world anyways) has a persistent connection these days, right? So maybe it doesn't matter whether we include the docs in the distro, and just let the users visit the docs on the web in a browser. Maybe that's acceptable.

What we want is a simple, WYSIWYG way to edit our docs that will export a plain html structure. We're looking at Amaya, maybe we'll do it that way, although that's a lot more work than what Helpndoc gave us. We just need text, links, images, etc. We don't really need fancy animations or any javascript, at least not yet. So we're trying to figure that out.

We played with Dokuwiki and Tikiwiki, but it takes me like twice as long to write/format documentation using wiki as it does using WYSIWYG tools. Plus I'm leery of any tools that claim to be able to export a wiki to straight html... can't remember if I've even seen such tools or not. I don't want to adopt yet another documentation tool, only to find that it hoses me the way helpndoc has several times now.