Matt and company,

I really like the way the docs are shaping up.  The layout looks nice and the disqus comment section is a really nice addition.  Is there a way to have an author be notified in some manner when a comment is left on a doc page that they wrote?  As the author of a page, I feel like I'm probably unlikely to return to that article very frequently as I'm already quite familiar with the subject matter.

I also second the idea of centralizing all things related to code examples.  The cookbook is a nice place, since new users are given a menu of things they can do right on the cookbook page.  I feel code examples are more likely to get checked out and used if there's an easy place to be made aware of their existence.

Finally, I think the cookbook could use one more section for extensions recipes, that is using the stuff in yt/extensions.  I'm thinking of the halo finders, halo profiler, light cone, EnzoSimulation class, etc.  The docs already have a section for extensions, but I think there's a distinction between the extensions docs and extensions recipes.  For example, I will write a doc page for the EnzoSimulation class, but also have a page on how to use this with the halo profiler that I think belongs in the cookbook.

Britton

On Wed, Sep 30, 2009 at 1:28 PM, Matthew Turk <matthewturk@gmail.com> wrote:
Hi guys,

I've been working in the evenings (and, today, during the day a little
bit...) on the documentation.  Britton, Stephen and Jeff have also
chipped in and written a bunch.

I've uploaded a new build of the docs (which will last until the next
svn commit, at which point it'll be wiped and replaced with whatever
is in SVN currently) to here:

http://yt.enzotools.org/doc/

There are two new features I wanted to mention:

 * The cookbook ( http://yt.enzotools.org/doc/cookbook/recipes.html )
is programmatically generated from the cookbook repository (
http://hg.enzotools.org/cookbook ) and images are generated
automatically as well.  All other locations of examples will be wiped
and either left empty or replaced with links or content
programmatically generated from the cookbook repository.  It is 100%
my fault, but we have too many scattered, sometimes broken, sometimes
outdated, undocumented examples all over the place.  This is my
attempt to fix that.

 * I've added comments to every page in the documentation using
disqus.com.  Currently you need an OpenID (gmail supplies this) to
comment.  All comments are aggregated on a single page on disqus's
site, or they can be viewed threaded-inline in the docs.  This can be
expanded to accept Facebook logins, but I was hesitant on that.  What
are y'all's thoughts?

Also, there are still some major blank spaces in the docs.  I'm
working on filling them in, as are other people (mentioned above).  If
you'd like to help out, pick out a spot, clone the yt-doc repo, add
text or images or whatever, and I'll give you push privs.  (Of course,
as soon as you clone a repo, you already have commit privs.  :)

-Matt
_______________________________________________
Yt-dev mailing list
Yt-dev@lists.spacepope.org
http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org