== Terminology used ==

new build process: the steps wherein a user goes from "I have nothing on my computer" to "first working instance of openplans, yay!"

upgrade process: the steps wherein a user goes from a working build of openplans to a new and different working build of openplans, with databases, data, configurations, etc. intact. (usually "I have a site, it works, but it's using older software and I want it to be on the good new stuff instead," or "I'm developing, and want to get the latest trunk.") It sounds like newsite.sh and newbuild.sh handle this case?

clean-reinstall process: the steps wherein a user goes from an old (possibly broken) openplans build on their computer to an entirely new one - all old data, port information, configurations, databases, etc. is *totally* wiped. the equivalent of doing an uninstall and then a new build process. I think this is what jhammel was talking about.

== deployment instructions ==

regarding http://www.openplans.org/projects/operations/openplans-deployment-instuctions 

1. intro sentence

 - "This page provides instructions related to the deployment of development, testing, and production instances of the full stack of the OpenPlans software suite, using the fassembler build tool."
 - maybe add "it is the procedure/configuration the TOPP team uses, and is recommended best-practice for others who want to run the openplans stack as well" for clarification if that's really what is intended, but the TOPP-specific stuff has to be taken out first... (read on)

2. deployment checklist (I followed the link):
 - this seems like a lot of TOPP-specific stuff, with practices we follow for openplans-the-stack development, geared towards the openplans.org and nycstreets deployment.
 - also, this is a stub (see the end of the page, starting with "Somebody who's done it should probably write this")
 - while I guess this could apply to non-TOPP teams who want to deploy their own openplans.org-like site, it very openplans.org specific (it directs people to check the milestones on our specific trac instance, to check the core user stories for our openplans.org-particular use-scenarios)
 -  Is the information on this page up to date? Maintained?
 - Are my comments accurate? Is it less TOPP-specific than I'm thinking? I could totally be missing something, probably lots of things.

3. deployment location and layout
 - by "sites," do you mean "all sites using openplans in general" or "sites that TOPPers working towards woonerf/openplans.org/nycstreets are making?" General "what is general, what is TOPP-specific questions throughout...
 - /usr/local/topp is a pretty TOPP-specific dir. ;)
 - deployment vs build: a deployment is an instance of a site (for instance, openplans.org) and a build is a version of software that this site could be running (for instance, build 1234 running on the current deployment of openplans.org)? want to make sure I'm on the right page.
 - the rest of this is beautiful and (I think) makes sense to me.

4. creating a new deployment

- again, /usr/local/topp is... kinda topp-specific. the varied url examples afterwards help, but is there a more generic recommended build directory, like /usr/local/mycompany/www.mysitename.org? or /usr/local/openplans/www.mysitename.org? or should people from outside TOPP be using /usr/local/topp/www.NotAToppSite.org?
- the rest of this is beautiful and (I think) makes sense to me, aside from the "are these great instructions written for TOPP requirements? non-TOPP requirements? TOPP requirements but non-TOPP strong-recommendations? strong-recommendations-for-all?" question.

== questions ==

three questions about the build process, and one about next steps:

1. what are the requirements vs the recommendations for building openplans? (is using fassembler a requirement? a recommendation? is having a certain directory structure common practice, or sufficiently important to functionality as to be made into an explicit "you should do this" instruction?)

2. can we script the requirements to make installation as easy and fast as possible? (with customization and documentation of options and flags you can set for various setups, and so on)

3. how does this experience differ across platforms, and how should build instructions and scripts be tuned to accommodate that (or at what point do we say "we support these platforms, if you want to run this in windows with cygwin, you're on your own")? ties into the question of what kind of external development/usage of the software beyond openplans.org and nycstreets we want to support, which... isn't yet clear to me, really.

next steps: I think the best way of hashing this stuff out efficiently is for a couple of people to go through and have a "fix the building process!" pow-wow - test on different platforms, tweak/rewrite shell scripts, flesh in functional (if not yet human-readable - that can come later, i'd be happy to do this on my own) documentation... is this a good thing to shoot for? is there something that should be done in the meantime? is there a better, more efficient option?