"... 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
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
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
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
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
wrote: 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