Good Examples of Build and Deployment Documentation

Question

Hi,

I'm in the middle of writing a build and deployment document for a major enterprise platform, and I would appreciate a good example to use as a template for how to structure the document. Can anyone point me towards a good example of a well written build document? It does not have to be an online document, but could also be included as part of an software distribution package.

Thanks, MagicAndi

Update
This is documentation for an enterprise platform, consisting of a number of separate solutions and configuration changes. This isn't something that can be done with a point and click installer or a single script for an application. Also, this is technical documentation aimed at other developers, NOT at end users. Apologies for any ambiguity in the initial question.

Also, I would appreciate answers that actually point me to examples, or give a full document structure (Sections to include, etc), as requested in the question, otherwise I will have to start downvoting. Thanks.

Answer 1

The Mozilla Build Documentation seems to be quite comprehensive, and well written.

Answer 2

Many Python modules have the following build document.

Download and expand the file.

python setup.py install

Many open-source packages have the following build document.

Download and expand the archive.

./config

make

make install

Those are really good build documents. And they're all over the internet.

Here's an outline of how web application deployment could work.

1. Prepare

   1. Install Apache.

   2. Install MySQL.

2. Install the application software. svn up, python setup.py install. We put this into /opt/app-x.y directories so that it's independent of all other considerations.

3. Create working directories and configure the application.

   1. Create the /www and /var directories, populate with necessary files. make_location.py. We provide a script that creates and populates these directories correctly and consistently. It's run with sudo.

   2. Edit the application settings file to name the server, database and provide credentials for DB access. We provide a template that actually works if the config is completely standard.

4. Create the schema. manage.py syncdb. We use Django, they provide this utility. Their idea is brilliant, and should always be used. Sometimes we're migrating from an old schema to a new schema. In that case, there are a few more steps.

5. Configure Apache. Copy the application-specific config file to /etc/httpd/conf.d directory or wherever it goes in your specific instance.

If you have to write more, perhaps your build procedure is too complex?

Answer 3

We manage a formal change control process that forces requesters to fill out a form that does a few things.

It helps the requester remember what kind of outages a build will create. It makes sure rollback and backup strategies are made for all new projects. It makes all relevant parties review the form once to catch any odd situations (Like a build requested at the same time a backup runs.)

Most importantly to you though, it contains instructions for the build itself. We do it by trying to stick to 10 or so steps as a maximum. Below are a few examples of what some steps might have in them:

Step One:

• Task Owner: Developers
• Task Description: Prepare a new build folder and provide to IT.
• Completed?: No

Step Two:

• Task Owner: IT
• Task Description: Post outage page on web portal. Run manual database backup.
• Completed?: No

etc.

After the change request is approved these steps are used as a checklist. We don't have to give many task details because they are just reminders for steps to be taken by trained staff. People creating software for public distribution would have to be much more specific.

Answer 4

I think the most important thing about this is that everything that can be automated should be automated. This means that if your build documentation ever has a step that is comprised of multiple, non conditional actions. Then you ought to provide a script that does all of those actions in one go. This goes a long way toward simplifying the build process.

Answer 5

You should start by walking through the build and deployment process yourself, writing down every single thing you do.

The documentation must include what your local, dev, and production environments look like, what steps are taken to get the source and compile it, and what steps are taken to actually deploy it.

Just make sure you are clear and use screen shots as necessary. Ideally someone who is unfamiliar with your environment should be able to read the docs and recreate the entire deployment. Don't take any bit of knowledge for granted, put it in the docs.

Answer 6

I will share my experience to contribute with some ideas that could be useful.

We use an Ant based build file (or set of files, but only one used as entry point to the process), deployment configuration in property files, a set of SQL scripts for creating the DB structure and initial data, and a very suscint deployment manual. The instructions basically are:

• config properties files for the specific environment
• run DB scripts
• run "ant deploy" (deploy task depends on tasks like clean, compile, undeploy)

The properties are splitted in three files: the first used for security specific properties, the second for application properties defined by the developers that aren't dependant on the environment, and the last one for environment specific configuration like paths, servers, ports, etc.

This escenario works fine. I know that Maven could improve this, just sharing my actual experience. I agree with Jack Ryan: everything that can be automated should be automated.

Answer 7

It really depends on your environment, but I would take a look at some "commercial" OSS projects. Just a few pointers to get you started:

• Spring dm server
• MuleESB

As far as I can see from their layouts, they all use Docbook as documentation source. The main advantage with Docbook (in comparison with Word) is that you can easily generate the content from various sources. It is quite hard to keep the documentation up-to-date with the actual application code so that your only hope is to generate as much as possible from the code/configuration files.