Version 8 (modified by japhb, 12 years ago)

Summarize and collate comments from linked #parrotsketch discussion

  • 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.
  • 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.