Plans/DocEnhancements

Front Page

  • more screen shots!
  • possibly eliminate Getting the Code/Dependencies? sections from main page (see first comment in Installation Instructions).
  • maybe one link to "Get the Code" or "Get yt" at the top. This could be a redundant link to the 'getting started' pages in the documentation.

Installation Instructions

  • There seems to be a number of pages that suggest that that is where you should go to get started (Installation Instructions, Getting Started in Docs, Getting the Code/Dependencies? sections on main page). These should be more concise, with one clear place to get started. matt: once the other things are dealt with, I'll add a GetTheCode? page.
  • move info about installing on specific machines (DataStar?, Red, etc.) to separate page.
  • maybe at the top, have a list of links for instructions for various machines/OSs. For example:
    • Mac OS X
    • Linux
    • Specific Machines
      • SDSC Datastar
      • SLAC Red
      • Your mom's Commodore 64 PET

Documention
general comment: 'next' and 'previous' buttons should include titles of pages they link to.

  • Introduction
  • Getting Started
    • should start with getting the code
    • above comments regarding a unified installation page
  • A Short Tutorial (maybe change to just Tutorial)
    • Getting Started
      • Getting into yt
        • add note about using 'from yt.mods import *'
    • Basic Objects
      • don't introduce fields until after introducing objects
      • add something like "What objects can we make?" or something like that, with a list of all objects (3d: grid, region, sphere; 2d: slice, projection)
      • all objects should be mentioned in this section with descriptions and code examples
    • Derived Fields
      • explain the convert function better in the defining your own fields section. An example where the convert function does more than just 'return 1' might help explain what it does.
      • what's a validator? I don't really understand it is. A one sentence definition would help.
    • Profiles
      • the note about making and plotting the profiles is somewhat confusing. If they can be plotted with pylab, why would we want to add them to a plot collection? Maybe the Plots section should come before this one, so there is already an established way of making plots. Also, can all these plots be made both ways? If not, the difference should be explained in the context of the situation in which I would want to use one over the other. If so, it should be stated that you can do this both ways, whatever the user likes best.
      • the 2D porfile section refers to using the plot collection, which is not something that has been covered yet. Given this, the plots section should definitely come first.
      • every argument given to the profile functions should be explained. Maybe in the example use variables and use the variable in the function call. Also, it may be useful to provide links to the function docs for each function.
  • "More plots" should be longer
  • Cookbook should include "plotting profiles" and not just "making profiles"