[yt-dev] Documentation Sprint

Cameron Hummels chummels at gmail.com
Mon Oct 28 18:16:50 PDT 2013


Hey everyone,

This is a status update after day one of the doc sprint.  We had a good
turnout with Matt Turk, Sam Skillman, John Zuhone, Jeff Oishi, Nathan
Goldbaum, and myself present.  We were able to get a lot done, some
synchronously, some asynchronously, over the course of the day.

Work has begun on restructuring the docs to make them more easily
navigable.  The front page has been cleaned up to have a limited number of
top-level options for users.  The installation page has been updated.  The
cookbook repository has been merged into the docs inline so that new users
can view (or execute) that as their introduction to the functionality of
yt.  Minor changes have occurred on the help pages and the developer pages.
 Significant effort has gone into making the docs more succinct and having
fewer overlap points (where some concept is explained more than once).  The
workshop materials were removed and many of the former top-level
directories (e.g. advanced) have been split up and redistributed into the
other code directories.  A new sample dataset was added to the
yt-project.org/data site by Nathan of one of his high-res isolated galaxy
sims--it's almost 3 GB, but it's a beautiful dataset for demonstrating some
cool functionality with real data.


CURRENT VERSION OF CODE
I've issued a PR to the yt-doc repo with many of these changes here:
https://bitbucket.org/yt_analysis/yt-doc/pull-request/110/updates-to-docs-after-day-one-of-the-doc/commits

You can view this version of the docs looks here (minus the api docs and
the bootcamp renderings):
http://green.as.arizona.edu:8080/


THREE TIERS OF INTERACTING WITH YT
We seemed to settle on grouping yt functionality into 3 tiers: visualizing
data, analyzing data, and examining data (accessing it at a low level).
 Sam Skillman made a cool illustration of this here:
https://docs.google.com/drawings/d/15aWmO71uHaxjx0qK5bMGxHir9wPI27Cgk-qG03Y00nc/edit.
 The plan is to have the docs reflect this hierarchy and to have it
show
up in the introductory statements on the front page.


CURRENT TASKS
--Nathan - Creating a set of notebooks to demonstrate how to use the plot
window and plot modifications effectively.  This will update the entire
plotting interface portion of the docs.  Also, create an introduction to
how to use notebooks from scratch.
--Jeff & Sam - Writing a notebook demonstrating how to use it for doing
real science, not just merely as a toy.
--Cameron - Going over the top-level docs with a fine-toothed comb looking
to update/clarify.  Restructuring the hierarchy of docs.
--John - Updating the Athena frontend; Documenting SZ analysis and particle
trajectories in the analysis modules section.
--Matt - Restructuring the hierarchy of docs.  Purging out-of-date
information.  Picking a new theme for the docs.

But there is still a lot left to do.  For those of you who want to
participate but don't yet know how you can assist, you can do a few things.

--Look over the docs and see if you find anything that needs fixing,
pruning, updating, etc.  Add an issue in the yt_analysis/yt repo and tag it
with documentation, so we know to fix it.  Or create an issue and fix it
yourself and PR it.  Really, the docs just need some attention to clean
them up.
--Look at the existing documentation issues on bitbucket.  Address one of
them.

COOKBOOK
I think we settled on a solution to the notebook vs script debate.
 Continue to use scripts for the simpler tasks in the cookbook and use
notebooks for more complex examples.  Right now I've split the cookbook
into Example Scripts and Example Notebooks for this task.  Tomorrow will be
spent adding more coding examples to both of these subdivisions.

GOALS FOR TOMORROW
Finish restructuring the docs.  Add lots more recipes (both notebook and
scripts) to the cookbook.  Address more of the issues from the bb list.

If you want to join us, come by IRC or google+ at 8amPST tomorrow, and
we'll put you to good use.

Cameron


On Sat, Oct 26, 2013 at 9:40 AM, Britton Smith <brittonsmith at gmail.com>wrote:

> Hi Cameron,
>
> Thanks for organizing this!  This will be very useful I think.  I will be
> traveling for most of Monday during the time of the sprint but should be
> able to participate on Tuesday.  It would be useful if you could provide a
> short summary of the events of the first day for those of us who can only
> join in on the second day.  Thanks again for doing this.  See you all there.
>
> Britton
>
>
> On Thu, Oct 24, 2013 at 2:16 AM, Cameron Hummels <chummels at gmail.com>wrote:
>
>> Hey everyone,
>>
>> Next Monday and Tuesday we will be having a documentation sprint to try
>> to beef up the yt docs (and docstrings) before the final release of the 2.x
>> branch when development (and documentation) will switch over to the 3.0
>> branch.  All developers are welcome to attend/participate for as much time
>> as they can spare.
>>
>> I know documentation isn't always glamorous, but I think this will be
>> pretty fun.  Furthermore, I think this will be very beneficial to the
>> community, in that it will be fewer frustrated users, fewer questions on
>> IRC and the mailing list, and better understanding for everyone of all the
>> features and functionality of the codebase!
>>
>> We will be meeting up as a Google + hangout over the course of those two
>> days, with periodic "check-in" meeting times to make sure everyone is on
>> the same page (see below for schedule).  Yes, I know it is early for
>> Pacific Coasters on a Monday @ 8am, but you can meet for a few minutes from
>> your bed without your camera turned off if need be.  We all know that
>> people have meetings and need to eat and such, so you are not required to
>> be in the G+ hangout constantly.  That said, people are encouraged to
>> remain in the G+ hangout throughout both days for fast turnover time if
>> they have questions/discussion or want to work on something new.
>>  Documentation tasks will be identified so that attendees can volunteer for
>> them at the various check-in meetings.  This way, individuals can work on
>> these tasks semi-autonomously.  The various things I think we should aim to
>> accomplish include:
>>
>> --Add documentation for features that are currently undocumented in the
>> yt codebase.
>> --Add documentation for new features from yt 2.5 to present (in
>> docstrings, cookbooks, and narrative docs as applicable).
>> --Fulfill the tasks identified in the BitBucket Documentation Issues
>> List:
>>
>> https://bitbucket.org/yt_analysis/yt/issues?component=documentation&status=open&status=new
>>  --Remove outdated information from the docs.
>> --Pare down multiple locations of how to do individual tasks, so as to
>> make maintainability easier.
>> --Fix any typos or mistakes in the content.
>>
>> SCHEDULE
>> Monday
>> --8am PST/11am EST: Initial meetup in G+ to discuss the goals of the
>> sprint and to layout the specific individual tasks which need to be
>> accomplished.  I'll include a template for a docstrings example, a template
>> for a cookbook example, and an example of a good narrative docs section.
>>  Developers will choose what task they want to work on.  Meeting should
>> take 30-60 minutes.
>> --11am PST/2pm EST: Status check, and reshuffling of projects as needed.
>>  15 minutes.
>> --2pm PST/5pm EST: Status check and conclusion for the day. 15 minutes.
>>
>> Tuesday
>> Same schedule as Monday.
>>
>> WHAT I NEED FROM YOU
>> Please write back to this email saying whether or not you're going to be
>> attending any/all of the sprint.  That way, I can invite you personally to
>> the google docs hangout to join up.  I may try to make this hangout
>> "on-air" so that it is recorded, and so if we go above the 10-person limit,
>> those unable to fit in the hangout can watch it streaming live.
>>
>> Before Monday, please think for a few minutes about things that you may
>> have noticed in the past that were lacking from the documentation, but at
>> the time you found them you didn't have time to fix.  If you identify
>> anything, please mark it down as a documentation task in the bitbucket
>> issue tracker so that we know to work on it next week:
>> https://bitbucket.org/yt_analysis/yt/issues?component=documentation&status=open&status=new .
>> We will be using this as our main means of tracking what gets accomplished
>> during the sprint.  I encourage you to look at the docs as well to look for
>> ways they can be improved.
>>
>> Thanks everyone, and I look forward to meeting with you next week!
>>
>> Cameron
>>
>> <https://bitbucket.org/yt_analysis/yt/issues?component=documentation&status=open&status=new>
>> --
>> Cameron Hummels
>> Postdoctoral Researcher
>> Steward Observatory
>> University of Arizona
>> http://chummels.org
>>
>> _______________________________________________
>> yt-dev mailing list
>> yt-dev at lists.spacepope.org
>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>
>>
>
> _______________________________________________
> yt-dev mailing list
> yt-dev at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>
>


-- 
Cameron Hummels
Postdoctoral Researcher
Steward Observatory
University of Arizona
http://chummels.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20131028/b21341a9/attachment.htm>


More information about the yt-dev mailing list