[yt-dev] 3.0 Documentation

[Cameron Hummels]

"... 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 at 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 at 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 at 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 at 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 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
>> >
>> > _______________________________________________
>> > 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
>>
>
> _______________________________________________
> 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/20131213/3b8a7c35/attachment.html>