* Separate documentation by purpose: (see discussion at http://irclog.perlgeek.de/parrotsketch/2009-11-17#i_1742133)
   * All documentation needed by users to effectively use anything covered by the deprecation policy should reside in the `docs/` hierarchy.
     * This includes end users, HLL developers, library authors, embedders, extenders, etc.  Basically any use other than creating and maintaining Parrot itself.
     * As `allison++` said, "someone treating Parrot as a blackbox"
   * The top level in `docs/` should be user-focused documents only.
     * Users shouldn't have to dig to find help getting started; experienced developers can easily handle an extra directory level.
   * Internals and Parrot developer documentation should be moved to `docs/internals/`.
   * Architectural overviews should be moved to `docs/pdds/`.
   * Inline documentation in `src/` should only include implementation details; the rest needs to be extracted out to `docs/`.
   * Tasklists and work notes should be moved to the wiki.
   * Any given API should be documented in just one file, and that documentation should be complete and consistent.
   * The Python docs were held up as a good example: http://www.python.org/doc/ and especially http://docs.python.org/3.1/extending/

 * Adjust the 'make html' generators Parrot::Docs::* to match the new paths.

 * Create a tutorial for Parrot (can be pulled in from various tutorials on the web)
 * Migrate (and update) the Parrotblog compiler tools tutorial into docs (http://www.parrotblog.org/2008/03/targeting-parrot-vm.html)

 * Index our documentation so it's easier for our users to search. POD provides an X<> tag for this.

 * Find all examples of PIR embedded in Pod documentation anywhere in the repository, and wrap them in PIR target blocks like this:


{{{
=begin PIR
     
 .sub main :main
    'MySub'("name" => "Bob", "age" => 42)    # Same!
 .end
  
=end PIR

}}}

For now, only do this with PIR examples that contain complete subs and are expected to work. Partial examples can be wrapped with PIR_FRAGMENT instead. Examples that aren't expected to work can be wrapped in PIR_INVALID or PIR_FRAGMENT_INVALID, and examples that should work but currently don't can be wrapped in PIR_TODO or PIR_FRAGMENT_TODO.

 * For bonus points, run {{{t/examples/pod.t}}} after you do this and fix any errors this finds in the sample PIR.