Thank you so much for taking charge of the docs. On a personal level I really appreciate your work, and on a professional level I'm happy to see someone handle the docs that is a bit more quality control oriented than the previous primary caretaker [me].
I have been assigned (or accepted) a couple tickets:
for documentation. What I wanted to do was, prior to writing the documentation in earnest, ensure that I understand the best place to put things. As it stands, in the last calendar year, the docs have had quite a bit of fluctuation: reorganization (by me), re-working the top level layout, and now a big push for a more conceptually clear organization (by you and Cameron.) My concern now is that now that we're taking a closer and more carefully considered approach to organization, I'm going to end up putting material in the wrong place.
For ticket #343, I can put the developer documentation with all the other Guilty Sparks (haha?) of developer documentation: http://yt-project.org/docs/2.2/advanced/developing.html , even if those get moved around (maybe to top level?)
For ticket #333, I am at a loss. The cookbook idea in the comments is good, so I will add a cookbook recipe, but where would a description of these go inside the narrative docs? The best place under "Analyzing" seems to be http://yt-project.org/docs/2.2/analyzing/objects.html but I think these are a bit advanced for that. Ideas?
For ticket #334, I think we need a whole new section on how to deal with fields that are on disk and that are derived. This would probably have to include "How does yt read in a data file, what does it do when it finds a field on disk, how can you control this behavior" and so on. Where should this go? Should I write the whole thing, or will someone work through it a bit with me?
For ticket #336, I am at a loss for where and why this would be documented besides "RAMSES data loading now works correctly in parallel." Should this section be reworked? http://yt-project.org/docs/2.2/analyzing/loading_data.html
Anyway, thanks again for all your help touching up the docs, reworking their organization and so on. I'm very eager to see what comes out of this big push, and I'm keen to write up my portions of it!
On Wed, Nov 16, 2011 at 1:21 PM, j s oishi firstname.lastname@example.org wrote:
Per today's developer meeting, we decided on a 15 Dec 2011 release date for 2.3. The only remaining outstanding tickets concern documentation, and we want to ensure that the documentation undergoes some kind of quality control before the release. Unlike the code itself, which can (and will) be submitted to automated answer testing, the documentation will need to be tested by actual humans. We decided the best way to go about this would be to have a potential pull request acceptor first test the documentation by reading it and attempting to use the new feature before accepting. This shouldn't take too long, and should ideally be done using the acceptor's own data (to ensure that at least some modification of the script is taking place).
If there are any questions or comments about this, let me know. If people not in the meeting this morning are satisfied with this, we'll just adopt it as we go to close the tickets sam has added here:
yt-dev mailing list email@example.com http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org