Ticket #781 (new cage)

Opened 6 years ago

Last modified 5 years ago

[CAGE] Copyedit docs/user/pir/*

Reported by: japhb Owned by:
Priority: normal Milestone:
Component: docs Version: 1.3.0
Severity: medium Keywords:
Cc: Language:
Patch status: Platform:

Description

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.

Change History

Changed 5 years ago by allison

Coke's nifty PIR, PIR_FRAGMENT, and PIR_INVALID for example checking would be a big help in keeping the examples up-to-date.

Changed 5 years ago by jkeenan

  • component changed from none to docs
Note: See TracTickets for help on using tickets.