On Mon, Jul 5, 2010 at 1:36 PM, <exar...@twistedmatrix.com> wrote: > On 08:23 am, j...@mumak.net wrote: >>On Mon, Jul 5, 2010 at 3:08 AM, <exar...@twistedmatrix.com> wrote: >>... >>>Thanks for your work on this release, and congratulations on getting >>>it >>>out the door. :) >>> >>>I'm curious about plans to update the documentation on the website and >>>distribute the .exe Windows installers. >> >>Oops, forgot to switch over the symlink for the docs. That's done now. > > Great, thanks! > > One thing that it looks like we missed again (and I'm not surprised, > it's not well documented) is the Google Analytics doc template changes. > This is mentioned on the APIDocs page, but maybe not described in > sufficient detail?
I think it's not so much lacking detail as leaving gaps for interpretation or not being step-by-step enough (which I guess is the same thing, but a subtly different goal). Following the documentation generation instructions was confusing for me because: * originally they were incomplete and messy * the "api documentation" and "general documentation" steps were conflated * at least one of the steps required a special kind of tree, which took me some time to figure out * I was using the last release and release 8.2.0 as a way of double checking that I was doing the right thing Things we can do now: * Update the current documentation so that it uses the correct template * Update the release process to be clearer (I think this is done now, but I can use the previous step to double check) * Delete APIDocs, or at least stop recommending it -- it's easier followed if folded in to the release doc >> >>I don't remember anyone saying anything about exes until now. > > These are mentioned on ReleaseProcess (Cut the tarballs & installers, > 3.4), but apparently only in one of the several places where they need > to be handled. This is the first release where we're trying to provide > them (#4427). > Ahh, ok, I see that now. I think if I'd received some sort of direct communication about it, I wouldn't have missed them. Other things we can do, now, to make this easier: * Upload the exes, re-issue the md5sum file * Add the exes to the Downloads page * Make a decision about whether we want the exes on the front page, act on that decision * Update the examples in the release process doc to include the exes * Update the release blog post pointing to the exes For both of these issues, a more satisfying solution would be to automate them, putting them outside the realm of human error. However, I think the interim steps listed above are worthwhile. I'll do these now, and email back when I'm done. I would greatly appreciate thoughts on the issues I raised in my original post. jml _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
