To aid in proofreading, I've created a public etherpad for us to collaboratively share notes:

https://etherpad.mozilla.org/jJqKGPZJ1t

If you find a docs issue and are not comfortable editing the docs yourself, just add it there and one of us will take care of it.  If you fix an issue, just mark the note as completed by striking it out.


On Tue, Jul 29, 2014 at 11:12 AM, Michael Zingale <michael.zingale@stonybrook.edu> wrote:
Cameron, if you assign me a section of the docs (preferably not cosmology-specific), I'll go through it this afternoon/evening and test out the code in it and correct any mistakes I see.

Mike


On Tue, Jul 29, 2014 at 2:10 PM, Matthew Turk <matthewturk@gmail.com> wrote:


On Jul 29, 2014 12:53 PM, "Cameron Hummels" <chummels@gmail.com> wrote:
>
> To respond to Britton's question, the things that I think are blockers on release are:
>
> --Update the documentation field list;  I started working on this three weeks ago and had something working roughly (dynamically generating the field list docs from the source code), but I encountered problems getting it to work for all of the frontend fields.  Matt took over, but I do not know its current state.
>
> --Add a description of how particle unions work, and demonstrate how to use them.  This should probably go in the "filtering data" page.  I tried this, but I do not know how to make a particle union nor can I figure it out from source.
>
> --Include more on the "fields" doc page on why particle fields are different than mesh fields, and in particular what happens when a particle field is added and the "deposit" fields that are generated from it.  And what these deposit fields mean (what is the diff between "cic" and "density", "count", etc.)
>
> --Update the "code support" page to accurately reflect what codes are supported, and what level of support is offered for each one.  Does anyone know the level of code support for each of the codes?

Yup, all of these are mine and I'm planning to issue a PR today.

>
> --Here is the most time-consuming step, and one that i've been doing for a couple of weeks (which is how I've identified many of the previous tasks for updating the docs:  
> Proofread the docs looking for things that are inaccurate or that have not been touched since 2.x.  I'm not so concerned with typos or that sort of thing--mostly just that there is wrong information in the docs.  I found a bunch of old stuff that hasn't been changed as late as last night reading through the docs.  The parts that are out of date are not always easy to correct (it's not just changing pf->ds, or changing pf.h to ds), it's usually just inaccurate information that needs to be updated, and sometimes it is on specific topics on which only a handful of people are up-to-date for 3.0.  This can mean actually trying to run code snippets that are in the docs (just as a new user would if they were to encounter that section) and see if it actually does what it is supposed to do, or if it breaks then fix it.  Not always trivial.
>

Aaron Smith stopped by IRC volunteering to help with this, too. (Thank you, Aaron!!!)

> So you can see why I'm hesitant to have things go out tomorrow.  I don't see these as trivial tasks, or making things "perfect", but things that new users of 3.0 *will* ask about.  Heck, I'm now a seasoned user of 3.0 and I don't know the answers to these (and want to know), as an example.  
>
> Cameron
>
>
>
>
> On Tue, Jul 29, 2014 at 9:36 AM, Matthew Turk <matthewturk@gmail.com> wrote:
>>
>> ...and I think they're mostly or exclusively on me. I have carved out time today to finish my sections up.
>>
>> On Jul 29, 2014 11:22 AM, "Nathan Goldbaum" <nathan12343@gmail.com> wrote:
>>>
>>> For what it's worth, the issues marked in red on the trello board were considered blockers a couple weeks ago.  I don't think any of the remaining blockers require code changes.
>>>
>>> On Tuesday, July 29, 2014, Britton Smith <brittonsmith@gmail.com> wrote:
>>>>
>>>> I don't think I can be asked to predict what bugs will shake out, but I will concede waiting for waiting's sake since we're trying to stick to a timeline.  However, I think we need to sort through the remaining trello items, blocking issues, and PRs that are supposed to make it in by 3.0 all be on the same page with what absolutely must get done before this release.  At the same time, let's not be perfectionists, here.  There will be further releases and things will continue to be fixed up over time.  Cameron, can you point to specific items that you think are blockers that won't get done on time?
>>>>
>>>>
>>>> On Tue, Jul 29, 2014 at 10:00 AM, Matthew Turk <matthewturk@gmail.com> wrote:
>>>>>
>>>>> I'm -1 on further delays. Looking at the blockers and the ones assigned to me, I will have them done by Wednesday. Which ones are the ones that will be problematic or that need to shake out? We've been in a light code freeze for over a week at this point, right?
>>>>>
>>>>> On Jul 29, 2014 3:22 AM, "Britton Smith" <brittonsmith@gmail.com> wrote:
>>>>>>
>>>>>> We shouldn't release until blocking issues have been cleared, and probably a day or two after that to let things settle and bugs shake out.  One final hangout/sprint to establish what exactly needs to get done before the release is probably a good idea.  Would anyone be up for doing that sometime this week?
>>>>>>
>>>>>> Britton
>>>>>>
>>>>>>
>>>>>> On Tue, Jul 29, 2014 at 6:50 AM, John ZuHone <jzuhone@gmail.com> wrote:
>>>>>>>
>>>>>>> I won't be able to help out with documentation for a few days (probably until next week), as I am away at a meeting and have some other things to attend to in addition. 
>>>>>>>
>>>>>>> If we push it to next week, I will be able to assist. 
>>>>>>>
>>>>>>> On Jul 28, 2014, at 10:45 PM, Cameron Hummels <chummels@gmail.com> wrote:
>>>>>>>
>>>>>>>> Hello,
>>>>>>>>
>>>>>>>> First I want to thank everyone for their hard work at getting 3.0 where it is in terms of functionality, bug fixes, and documentation.  However, I'm concerned that there are still several things that need doing in the documentation prior to release of 3.0.  
>>>>>>>>
>>>>>>>> https://trello.com/b/Y5XV4Hod/yt-3-0
>>>>>>>>
>>>>>>>> Beyond that, I think once those things are done, we need some proofreading of the docs, because I'm not convinced there aren't still sections that are out of date and reflecting 2.x versions of the code.  Proofreading (and subsequent correction) may take a while.  
>>>>>>>>
>>>>>>>> I think it behooves us to push back the release a few more days until we make sure this is where we want it to be.  This is a major release with major API breakages, and I want to make sure the documentation actually reflects the codebase, so new users and new converts to 3.0 don't get confused.  I certainly was confused when i first moved over because there are a lot of significant changes that it's easy to forget after using it for a while and being as tied into the community as we all are.
>>>>>>>>
>>>>>>>> What do people think?
>>>>>>>>
>>>>>>>> Cameron
>>>>>>>>
>>>>>>>> --
>>>>>>>> Cameron Hummels
>>>>>>>> Postdoctoral Researcher
>>>>>>>> Steward Observatory
>>>>>>>> University of Arizona
>>>>>>>> http://chummels.org
>>>>>>>> _______________________________________________
>>>>>>>> yt-dev mailing list
>>>>>>>> yt-dev@lists.spacepope.org
>>>>>>>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> _______________________________________________
>>>>>>> yt-dev mailing list
>>>>>>> yt-dev@lists.spacepope.org
>>>>>>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>>>>>>
>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> yt-dev mailing list
>>>>>> yt-dev@lists.spacepope.org
>>>>>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> yt-dev mailing list
>>>>> yt-dev@lists.spacepope.org
>>>>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>>>>
>>>>
>>>
>>> _______________________________________________
>>> yt-dev mailing list
>>> yt-dev@lists.spacepope.org
>>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>>
>>
>> _______________________________________________
>> yt-dev mailing list
>> yt-dev@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
>
> _______________________________________________
> yt-dev mailing list
> yt-dev@lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>


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




--
Michael Zingale
Associate Professor

Dept. of Physics & Astronomy • Stony Brook University • Stony Brook, NY 11794-3800
phone:  631-632-8225
e-mail: Michael.Zingale@stonybrook.edu
web: http://www.astro.sunysb.edu/mzingale

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