Writing documents about migration from Perl 5 to Perl 6, random thoughts.

Original document written by Juerd on 2005-10-14.

Feel free to copy this to a wiki or something like it. Let me know, though.


- Avoid negative feelings about the change. All changes are
  incompatible, or else they wouldn't be changes. Leave off the
  "incompatible" flags. There are no warnings, traps, caveats and
  gotchas for informed people. So inform people, but without the terror.

- Perl 6 has many interesting new features and possibilities that will
  make a programmer's life much easier. However, the changes in existing
  features are overwhelming by themselves. Present the migrant with what
  they need to migrate, and let them learn the details later.

- Provide examples. Lots and lots of examples. Never explain changed
  syntax without providing an example, but also always provide an
  example when explaining changed syntax. Side-by-side examples are
  great for comparison. Perhaps colour coding the changes is a good
  idea.

- Perl 5 is old, and thus past tense. Perl 6 is here now by the time
  your document will be needed, so consider it present. Describe things
  as if you are a history teacher: things have changed.

- Explain that Perl 6 is not a new version of Perl 5, but a new language
  that shares only the philosophy of Perl. Explain why additions to Perl
  5 were not possible, and why the name is still Perl anyway. This will
  be hard, but imo has to be done.

- Explain how to convert existing code first, and then explain how to
  use new idioms to make life more fun. Try not to interleave these two
  aspects.

- With every change described, explain why the change was made. The new
  way of doing things is more powerful, more concise or more consistent
  with something else, but it's always for a reason. Knowing the reason
  makes information stick better.

- Assume knowledge of OO when talking about migration of OO code,
  because the entire underlying model has changed. There is very little
  use in trying to explain the Perl 6 equivalent of bless, even if it is
  exactly the same. There were many methods of creating accessors, and
  they need to be discussed, but they all migrate into the new
  automatically built accessors.

- Don't go into personal preference. Some people want to have whitespace
  between aggregate and index, but they can't. It's not needed to
  convince these people with a migration document. They either cannot be
  convinced, or they convince themselves.

- Nobody in the entire world uses Perl 4 anymore. Or at least, assume
  so. That makes everything much easier. Still, when a perl4ism was
  still possible in Perl 5, explain that the long deprecated or frowned
  upon feature or syntax is now entirely gone. No more &foo to call a
  sub, and certainly no do foo.

- If a feature is entirely gone, just saying so suffices. There's no
  need to draw attention. If people need these features, they can always
  continue to use Perl 5.

- There is more to Perl than the language. There is also the compiler
  and the virtual machine. The debugger, the documentation (and its
  format) and the standard modules. And, of course, the community. How
  best to deal with Perl 6 online, where Perl 5 might still be
  prevalent. Advise to use tags like "[P6]" and "[P5]" hoping there will
  be a single standard throughout the internet.  The tags will
  automatically die in a few years.

A possible chapter structure (still very bare)

1. Why Perl 6 was needed (brief!)

2. Syntax
2.1. Variables
2.2. Literals (numbers, strings)
2.3. Control structures
2.4. Subs (simple signatures)
2.5. Operators

3. Context

4. Regexes --> Rules

5. OO 

6. Idioms (Perl 5 idioms and Perl 6 equivalents)

7. Documentation
7.1. Standard documentation structure 
7.2. Documentation format

8. Tools
8.1. Debugger
8.2. Benchmarks
8.3. Profilers
8.4. Module installer

9. Neat new stuff (brief!)
9.1. Multi subs
9.2. Junctions
9.3. ...