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