|Version 7 (modified by japhb, 5 years ago)|
- All top-level docs/* files should be user-focused. Put internals and developer documentation in docs/internals/... (users shouldn't have to dig to find help getting started, experienced developers can easily handle an extra directory level).
- 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)
- Separate documentation by purpose: inline documentation is implementation details, PDDs are architectural overview, documentation in docs/ is for users (Some discussion at http://irclog.perlgeek.de/parrotsketch/2009-11-17#i_1742133)
- 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.