"... given that there is already so much that needs to be documented, I don't think adding epsilon on top of that is a big deal."  

This is exactly the sentiment that I was trying to avoid.  The longer the docs are out of date, the easier it is to justify not documenting that newest push that one makes to the codebase.


I understand that things are busy with the unit refactor, but I would say that as soon as it is accepted we should aim to have fully updated docs that are viewable to the public.  

Matt, I can try to test the cookbook recipes if that makes it easier.

Cameron





On Fri, Dec 13, 2013 at 9:12 AM, Nathan Goldbaum <nathan12343@gmail.com> wrote:
I agree with Matt.  If the 3.0 docs were only somewhat out of sync that would be one thing, but there's about a year's worth of work that needs to be covered before the docs are correct.

I understand your concern about documenting new features, however given that there is already so much that needs to be documented, I don't think adding epsilon on top of that is a big deal.

On Friday, December 13, 2013, Matthew Turk wrote:
On Fri, Dec 13, 2013 at 10:37 AM, Cameron Hummels <chummels@gmail.com> wrote:
> Sounds good, but I guess I don't understand why the 3.0 docs aren't yet
> buildable.  I can build them locally.  The only thing that prevented me from
> doing this is that I had to pip install the new bootstrap theme in order for
> them to not fail.  Is this what you mean, Kacper?
>
> I understand not wanting to have out of date docs available to the user
> base, but i'd love to get something up so people can document new changes to
> the code as they make them.

I agree with having the docs, but I worry that having *incorrect* docs
will be more damaging, particularly to perception, than no docs.

> Let me know if you need help on this, Matt.

I definitely do!  The best way to get started is to go through the
cookbook and make sure all the recipes work; I did this at one point,
but I may have missed a few, and I know a few have been updated in the
2.x repo.

Today after the conference call I can devote some cycles to this.

-Matt

>
> Cameron
>
>
> On Fri, Dec 13, 2013 at 6:42 AM, Matthew Turk <matthewturk@gmail.com> wrote:
>>
>> Hi Cameron,
>>
>> Thanks for taking this on!  I think that we should definitely push up
>> some 3.0 docs (which it sounds like Kacper is working on) but I'm not
>> sure that we should link them *until* they are mostly up to date.
>> Fortunately the cookbook process and the IPython Notebook process
>> won't pass until they are, so that's good.
>>
>> Once the AGORA telecon is over today I should be able to spend some
>> time hitting the easy changes to the docs that should bring them
>> mostly up to speed.  One thing we'll need to do with 3.0 that we
>> haven't in the past is emphasize much more strongly the developer
>> aspects, as some areas of the code -- while cleaner -- are different
>> in some key ways.
>>
>> -MAtt
>>
>> On Thu, Dec 12, 2013 at 6:34 PM, Cameron Hummels <chummels@gmail.com>
>> wrote:
>> > Hello everyone,
>> >
>> > Now that the bulk of the development is moving over to the yt-3.0
>> > branch, I
>> > propose we have the yt-3.0 docs available on the website.  Right now, a
>> > yt-3.0 branch exists in the yt-doc repository, but there are very minor
>> > changes in it relative to the yt 2.x documentation.  Unfortunately,
>> > there is
>> > no public way to view these documentations aside from downloading the
>> > repository and building locally.  I think by putting the 3.0 docs on the
>> > webpage, it will make it more likely that people contribute docs when
>> > they
>> > contribute new code changes, whereas if we wait too long, the codebase
>> > may
>> > get considerably out of sync with the docs.
>> >
>> > I think this will only require a slight change to the buildbot targets
>> > by
>> > Kacper.  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
>
>
>
>
> --
> 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




--
Cameron Hummels
Postdoctoral Researcher
Steward Observatory
University of Arizona
http://chummels.org