Changes between Version 7 and Version 8 of DocsTasklist

Show
Ignore:
Timestamp:
11/24/09 23:37:40 (5 years ago)
Author:
japhb
Comment:

Summarize and collate comments from linked #parrotsketch discussion

Legend:

Unmodified
Added
Removed
Modified
  • DocsTasklist

    v7 v8  
    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 
    214 * Adjust the 'make html' generators Parrot::Docs::* to match the new paths. 
    315 
    416 * Create a tutorial for Parrot (can be pulled in from various tutorials on the web) 
    517 * Migrate (and update) the Parrotblog compiler tools tutorial into docs (http://www.parrotblog.org/2008/03/targeting-parrot-vm.html) 
    6  
    7  * 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) 
    818 
    919 * Find all examples of PIR embedded in Pod documentation anywhere in the repository, and wrap them in PIR target blocks like this: