petdance/scratch — Issue #594: [CAGE] Copyedit docs/user/pir/*
Author: petdance
Created: 2011-11-14 06:11:54+00:00
State: open
Labels: cage, docs, Pri-normal, Sev-medium

These introductory docs are in need of some cleanup, copyediting and so forth. In particular:
* The docs claim to have last tested the example code with Parrot 0.8.1. The example code should be tested with a current parrot, and the compatible version notices updated.

* Several places compare confusingly against the behavior of ancient Parrot or PASM as if the user knows the older behavior already. As these are introductory docs with an audience of users first learning Parrot in the modern era, these comparisons should be removed where unnecessary. Where the comparisons are still valuable (as when explaining what sugar PIR adds over raw PASM), they should be reworded with the target audience in mind.

* Some paragraphs and sections appear to have been only partially edited at various times, so that later sentences refer to wording that no longer exists in earlier sentences. For example, I've already fixed one instance in which PMC is defined as "Polymorphic Container" and then a joke is made about M standing for "Magic".

* A few places refer to "previous examples" that don't exist in the document; if these refer to other documents that should be read first, this should be explicitly noted.

* Finally, a basic English prose copyediting pass should be done so that each document flows well.

Originally http://trac.parrot.org/parrot/ticket/781 by japhb (@japhb)