More Detail on How You Can Help Expand Lovelace: An Ada Tutor

Here are the steps I'd like you to take if you're seriously considering creating new Lovelace lessons:
  1. Look at the lesson "to do" list. I would want you to create one of the first lessons listed as `not done at all'. I'm happy to reorder the lessons-to-be-done as long as the tutorial user could readily understand the order. Obviously, you need to be competent in the material before you create a lesson for it!
  2. Look at the mklesson user guide and the pages linked to it; does it make sense? I expect volunteers to use mklesson so that our lessons will look similar.
  3. Skim through all of the current lessons so you'll see what the tutorial user knows (and doesn't know). If there's some material that you need, but wasn't introduced where it "should have been", let me know. For example, access types are likely to be added to the "types" section, but only if someone really needs them.
  4. Find out if you have a system where you can publicly export WWW pages. This problem can be overcome (I have that problem as well), but it's good to know ahead of time.
  5. If, after doing this, you decide that you're willing to put in the time, please email me (David A. Wheeler) at dwheeler@dwheeler.com. Please tell me that you'd like to develop some Lovelace lessons, and what you'd prefer to work on. We'll eventually agree on a specific ``lesson you'll do'' (picking just one). I will act as a "lock" so that only ONE volunteer will be assigned any specific lesson.

My main concern with volunteer-created lessons is that I want to ensure high quality; I'm sure you do as well. The problem is that, naturally, I don't know the volunteers and they don't know me (yet).

I think the best way to promote quality is to use this process once we've agreed on a lesson for you to do:

  1. Create 2 sections completely and a list of all the sections you plan to do (so both specifics and lesson structure are obvious). I'd give you a "due date"; my guess is 2-3 weeks should be enough time for this first cut, with less time welcome.
  2. Let me review your lessons & give you feedback (generally within a week or two). It'd be great if you could get other friends to look at your work as well.
  3. Presuming that things look good overall, complete the lesson; I suspect a "due date" 2-3 weeks later would be sufficient.
  4. Let me review the completed lesson. After fixing any problems, and assuming it's reasonably good, we'll post it. Your name will be be given prominent credit for the lessons and sections created by you.
  5. If you're game for more, we'll start the process over again. At this point we'll know a lot more about each other and we'll probably be much more comfortable working together.

I think there are at least two advantages to this process:

  1. Quality is always improved through review by others. I do this myself; I asked four people to review Lovelace before I put it on-line.
  2. If there's some systemic problem or misunderstanding, we can catch it early. I'm sure your time is valuable, so we don't want to waste it!

Finally, here are some rules-of-thumb for your lessons:

  1. A lesson shouldn't cover EVERY issue; it's better to cover the key issues, hint at what else is available, and later cover the more sophisticated or complex areas. For example, the "types" lesson certainly doesn't cover everything about types. Later lessons can introduce more advanced topics.
  2. Don't make sections too long; sections should be about the same length as existing sections. Nearly all sections should end in a quiz, and the quiz should stress some critical aspect of that section.
  3. Simplify where you need to. For example, a BNF you show needn't be the `full' bnf. If you use a BNF at all, link to "bnf.htm".
  4. Ensure that the lessons have the same "look and feel" as the other lessons they link to. If you're using mklesson (and you probably should), use the same "template" and "default" files as the rest of the lessons.
  5. Make the text as clear as possible.
  6. Be careful to follow normal HTML rules. In particular, be careful of the characters <, >, and &, since they must be treated specially (see an HTML primer for what to do instead). Also, please use Weblint (or some similar program) to check your .htm files, and try to fix the problems it finds. I found some serious errors in my posted files with Weblint.
  7. Whenever you use Ada examples, put them in separate files and use the new <TEXT FORM=PRE FILE="filename"> command of mklesson. The TEXT command will automatically translate the above special characters. If they are complete compilation units, have the filenames end in ".ads", ".adb", or ".a"; that way they can be automatically checked by an Ada compiler.
  8. Use underscores per normal Ada convention, but be aware that underscores may not be visible if they are a hypertext anchor (many browsers underscore such links). In particular, be careful with underscores in quiz questions.
  9. Include graphics if they'll help illustrate your points, but be sensible. Try to make the text understandable without the graphics, since there are people using text-only browsers. Provide brief alternative text for text-only viewers, like "[Image - X and Y are descendents of W]". To reduce the time it takes to see the graphics, use interlaced .gif files and include HEIGHT= and WIDTH= commands.
  10. Read my Lovelace organization notes, and make sure that your lessons are consistent with them.
  11. Avoid language-bashing. Compare and contrast Ada with other languages if it helps in understanding some issue, and feel free to point out a specific Ada strength or a specific weakness in another language. However, remember that all languages have strengths and weaknesses. Don't make broad claims like ``Ada is always better than language X''; such claims are rarely true for any language. I use Ada, C, C++, Perl, and many other languages as the task demands, and create my own languages if they help me. I believe that the professional approach is to use the ``right tool for the job'', taking all factors into account.

Thanks for your interest!

--- David A. Wheeler (dwheeler@dwheeler.com)

You can Return to the Lovelace home page.

This page was last modified 1-February-1995.

David A. Wheeler (dwheeler@dwheeler.com)