Amy KurtzmanTechnical Writer

Writing Sample

P.O. Box 1865 • Cupertino, CA 95015 • 408-313-1064email: amk.writes@gmail.com • web: http://www.amykurtzman.com/

P .O . BO X 1 8 65 CU P ERTI NO , C A 9 50 1 5

tel 4 0 8. 3 1 3 . 1 06 4 email am k .w r i t es @g ma i l .co m web h t tp : / /w w w. amy k ur t z ma n. co m/

AMY KURTZMAN P R OF IL E Innovative, detail-oriented technical writer seeking a position where I can leverage my background in technical

writing and software development to contribute to the company’s success.

E X P E R I E NCE QUALI TY R AT E R, GOO GL E , I NC. MO UNTAI N V I E W , CAL IFOR NIA 2 0 0 5– 20 0 6 ( CO NT RA CT)

Analyzed and researched search engine results for specific queries. Evaluated relevance and usefulness of web pages for specific queries

according to a classification scale and detailed criteria provided by Google.

Performed comparative analysis and ranking of sets of search engine

results. Worked with fellow team members to resolve disagreements on categorizations and achieve a consensus. Position required self training by

reading extensive project manuals. Project-based, part-time position.

SOFTWARE ENGINEER, KAISER ELECTRONICS, INC., SAN JOSE, CALIFORNIA 1993–1999, 2001 (CONTRACT) Using object-oriented methodology, designed, developed, tested, and

documented real-time, embedded graphical cockpit-display software for

F18E/F aircraft and Comanche helicopters. Designed, developed, and tested PC-based test tools and utility programs. Developed automated test

scripts, test procedure documents, and test reports. Participated in all

phases of the software development life cycle. Wrote software in Ada, C++, and the proprietary, hardware-specific assembly language for a custom

graphics engine. Reviewed software component design, code, test plans,

and documentation for technical accuracy and adherence to program standards. Produced all documentation using Adobe FrameMaker and

Microsoft Word according to strict customer-provided style guides.

TECHNICAL WRITER (INFORMATION DEVELOPER), IBM, INC., PERSONAL PRODUCTS DIVISION, BOCA RATON, FLORIDA 1992–1993 Updated a programming guide and reference manual for the OS/2 Graphics

Programming Interface API. Produced single-sourced printed manuals and

online help using BookMaster and Interactive Presentation Facility (IPF) to

create multiple products from the same set of input files. Wrote documents according to the company style guide and The Chicago Manual of Style.

E DUC AT I O N M.S., Library Science—University of Southern California, Los Angeles

B.A., Mathematics and Computer Science—California State University,

Long Beach

B.A., Spanish—San Francisco State University

A.A., Technical Writing—De Anza College, Cupertino, California

Certificate in Object-Oriented Programming—University of California,

Santa Cruz Extension, Silicon Valley

SK I LL S

Adobe Products FrameMaker Photoshop Illustrator InDesign Flash Dreamweaver

Microsoft Office Word Excel PowerPoint Outlook Access Project

Style Guides The Chicago Manual of Style Apple Publications Style Guide Microsoft Manual of Style for

Technical Publications Military Standards

Tools and Languages C C++ Objective-C Cocoa (Apple framework) Java JavaScript XML DTD HTML XHTML CSS SQL Xcode UML

Version Control Systems Subversion CVS

Platforms Windows Unix Mac OS X

About This Writing Sample

Getting Started With Version Control Using Subversion is an article I wrote that describes how to install and use Subversion, a widely used version control system, on Mac OS X v10.4 in conjunction with Xcode, the Mac software development environment. The article is targeted to readers of MacTech Magazine: The Journal of Macintosh Technology. The magazine publishes technical articles for readers ranging from beginners to experts who are interested in the Mac platform beyond the user level.

The article is formatted for submission to a magazine editor, with all figures and tables placed at the end of the article and notes regarding their placement interspersed with the text.

P.O. Box 1865 1st U.S. Rights

Cupertino, CA 95015 ©2006 by Amy Kurtzman

408.313.1064 2233 words amy@kurtzman.com

Getting Started With Version Control Using Subversion

By

Amy Kurtzman

Have you ever made a change to your software project that turned out to be a

bad idea and wished you could easily undo it? Have you ever wished you could go

back in time and make things the way they were a week ago, back when everything

was running smoothly? Those fantasies can come true in the future if you start using

a version control system to manage your software today.

Version control systems keep track of the changes made over time to a set of

files. A version control system documents the change history of your project and

allows you to go back in time to easily recreate any previous version of your project.

Although most commonly used for files containing software code, any type of

file can be managed with a version control system. For example, you can use a version

control system to track changes to your documentation and graphics files.

In this article, I’ll show you how to use Subversion, one of the newest free open-

source version control systems.

Kurtzman/Page 2

Basic Concepts

Subversion stores your files in a directory called a repository. Subversion is very

flexible and allows you to design a repository arrangement that suits your needs. A

repository can house files for one or more projects, but you also have the option of

creating multiple repositories so you can store each project in a separate repository.

Subversion operates on a client/server model. You use a client tool to interact

with the server, which in turn accesses the repository to carry out the commands you

issued. The Subversion client tools are command line programs that are run from a

Terminal window. Subversion includes several client tools; svn and svnadmin are the

tools you will use most often.

When you work on a managed project, you cannot directly modify the files

stored in the repository. Instead, you must make all of your changes in your own copy

of the project files. This copy is called your working copy, and you obtain it by

checking it out of the repository.

After you make changes to your files and want store them in the repository, you

“commit” the changes. The commit command sends changes from your working copy

to the repository.

A number of tasks, including initial repository setup and project checkout, can

only be accomplished using the Subversion client tools. However, once a project is

stored in a repository, you can synchronize your working copy directly from Xcode,

Apple Computer’s integrated software development environment.

Installing Subversion on Your Macintosh

Apple recommends installing Subversion using DarwinPorts, a free utility for

installing open-source software packages. DarwinPorts makes installing Subversion an

incredibly easy, one-step process.

Kurtzman/Page 3

By default, both DarwinPorts and Subversion are installed in /opt/local/bin.

The DarwinPorts installer automatically adds this directory to your search path. You

need to remember this location because you will have to enter it each time you set up

version control for an Xcode project. If you do forget where they are located, or even

whether or not you installed them, you can type the commands which port or which

svn in a Terminal window to find DarwinPorts or Subversion, respectively.

Install DarwinPorts

If you don’t already have DarwinPorts installed on your Mac, the first thing you

need to do is download and install it. To install DarwinPorts on your Mac:

1. Download DarwinPorts from http://darwinports.opendarwin.org/getdp/.

2. Run the installer.

3. Open a Terminal window, and type the following command to synchronize

with the OpenDarwin servers:

$ sudo port –v selfupdate

Synchronizing with the OpenDarwin servers is an optional step at this point,

but doing so does give you the assurance that DarwinPorts installed correctly on your

Mac. You should also run this command periodically to keep your DarwinPorts

installation up to date.

Install Subversion

Once you have DarwinPorts installed on your Mac, you can use it to install

Subversion. To install Subversion on your Mac, simply type the following command in

a Terminal window:

$ sudo port install subversion

Managing Your Project With Subversion

Now that you have Subversion installed on your Mac, you are ready to start

Kurtzman/Page 4

using it. To manage a project with Subversion, you need to create a repository and

then import the project files.

Although Subversion can manage any number of projects in a single repository,

for a couple of reasons I prefer to have a separate repository for each project. First, it

is easier to keep things organized when you limit the repository to one project or

perhaps a set of very closely related projects. And second, Subversion uses a single

version numbering sequence for the entire repository. Each time you commit changes

to the repository the next sequential version number is assigned, regardless of project.

If you store multiple projects in a repository, the gaps in version numbers on a project

can be confusing.

Create a Repository

To create a repository, you use the command svnadmin create. The command

format is svnadmin create path/to/directory. If the directory you specify does not

already exist when you issue the command, it will be created automatically. For

example, if you want to create a repository in a directory called mysvnrep located at

the top level of your directory structure, type the following command in a Terminal

window:

$ sudo svnadmin create /mysvnrep

Design Your Repository Layout

As the repository administrator, you create the directory structure for the files

stored in your repository. Many Subversion administrators create a main directory for

the project that contains subdirectories called trunk, branches, and tags. This

convention is recommended in the Subversion manual. If you use this scheme, your

directory structure will look like this:

/myproject

Kurtzman/Page 5

/myproject/trunk

/myproject/branches

/myproject/tags

Use the trunk subdirectory for the main line of code development, the branches

subdirectory for diverging lines of code (such as experimental versions or special

purpose versions), and the tags subdirectory for versions that mark significant

progress (such as releases or other milestones).

Import the Project

The next step is to place the project files in your repository. The easiest way to

accomplish this is by placing them in a temporary directory structure that mirrors the

repository layout you want to use. You can do this by either typing commands in a

Terminal window or creating new folders in a Finder window and then dragging copies

of your project files into the appropriate folders.

If you are starting a new software project and don’t have any code yet, create

the project with Xcode and then copy the initial set of files over to your temporary

directory structure.

To create a temporary directory structure with Terminal and move copies of

your project files into the /temp/trunk subdirectory, type in the following command

sequence:

$ mkdir /temp

$ cd /temp

$ mkdir branches

$ mkdir tags

$ mkdir trunk

$ cp -R /original/project/directory/path /temp/trunk

Kurtzman/Page 6

Remember to include copies of the Xcode project.xcodeproj file and your nib

files. Subversion treats file packages such as the project.xcodeproj file and nib files

as directories. You cannot use Xcode to add directories to a repository; the only way

you can get directories into a repository is by importing them using the svn import

command.

Before proceeding, you should examine the /temp/trunk directory to make

sure it only contains files you want under version control. Delete any files from the

/temp/trunk directory that you do not want under version control, such as a build

directory.

Once the temporary directories are set up, you can import it all into Subversion

with a single command:

$ svn import /temp file:///mysvnrep/myproject -m “initial import”

Now your repository is ready to work with, and you can delete all of the

temporary directories and files that you made.

Check Out a Working Copy

To make changes to a managed project, you must check out a working copy.

Since this is the first checkout of your project, request the code from the

/myproject/trunk directory of the repository. In a terminal window, type the

following command to check out a working copy and place it into a working directory

called /myproject:

$ svn checkout file:///mysvnrep/myproject/trunk /myproject

Managing Your Project With Xcode

Now that your project is stored in a repository and you have a working copy

checked out, you can begin using Xcode to manage the day-to-day changes in your

code. At this point you rarely will need to use the command line tools. This section

Kurtzman/Page 7

explains how to set up Xcode to use version control, determine the status of each file

in your working copy, and use Xcode menu commands to interface with your

repository.

Configure Your Xcode Project to Use Subversion

Before you can use Xcode to access your repository, you must tell Xcode that

the project is under version control and that you want to use Subversion. Each Xcode

project you want to manage with Subversion must be configured individually.

To configure a project for use with Subversion, open the project in Xcode and

then select SCM > Configure SCM from the main menu. This command opens the

General panel of the project info window, where you will set your version control

options. Towards the bottom of the window, select Subversion from the SCM popup

menu and check the box labeled Enable SCM. Finally, click the edit button next to the

SCM System selection popup to tell Xcode where the Subversion tools are located on

your system. If you used DarwinPorts to install Subversion, you need to set the

Subversion Tool Path to /opt/local/bin/svn, as shown in Figure 1; if you installed

Subversion using another method, set the path accordingly.

Insert Figure 1 here

View File Status

As you work with your code, you need to know the current status of each file.

Xcode can display file status in several ways. To add a column that shows the status

of each file in the Groups & Files pane, choose View > Groups & Files Columns >

SCM. To add a similar column to the detail view, choose View > Detail View Columns

> SCM. Figure 2 shows an Xcode project window that has these columns visible. You

can also see file status in the SCM smart group in the Groups & Files pane.

Insert Figure 2 here

Kurtzman/Page 8

Xcode indicates the current status of each file by placing a one-character code

next to the file name. These codes are the same ones used by the Subversion

command line tools to indicate file status. Knowing the meaning of these codes is key

to understanding the current version control status of your project. Table 1 lists the

codes and their meanings.

Insert Table 1 here

Interact with the Repository

Using Xcode, you interact with your repository by choosing commands from the

SCM menu on the main menu bar (see Figure 3). You can choose commands to

operate on either selected files or on the entire project. When you first start using

Subversion, you will only need to use a few of the commands that are available on the

SCM menu.

Insert Figure 3 here

To get the current status of your working copy as compared to the files in the

repository, choose SCM > Refresh Entire Project.

To update each file in your working copy to match the corresponding file in the

repository, choose SCM > Update Entire Project. To update individual files, select the

files in the Groups & Files pane and then choose SCM > Update To > Latest.

To copy the changes in specific files to the repository, select the files and then

choose SCM > Commit Changes. To copy all of the changes in your working copy to

the repository, choose SCM > Commit Entire Project.

When you create new files, add them to the repository by selecting the files in

the Groups & Files panel and then choosing SCM > Add to Repository. This

command schedules the files to be added to the repository—they will be added

automatically the next time you choose SCM > Commit Entire Project. Alternatively,

Kurtzman/Page 9

you can choose SCM > Commit Files while the files are selected to add them to the

repository.

Conclusion

In this article, you learned the basics of version control, and how to set up a

Subversion repository and work with a managed project in Xcode. To learn more about

version control using Subversion, consult these resources for detailed information:

Apple Computer, Xcode 2.3 User Guide.

http://developer.apple.com/documentation/DeveloperTools/Conceptual/XcodeUserG

uide/Contents/Resources/en.lproj/index.html.

The Subversion Website, http://subversion.tigris.org/.

Ben Collins-Sussman, Brian W. Fitzpatrick, and Michael Pilato, Version Control

with Subversion. http://svnbook.red-bean.com/.

Kurtzman/Page 10

Figure 1: Setting the path to the Subversion tool

Kurtzman/Page 11

Figure 2: Viewing File Status in the Xcode Project Window

Kurtzman/Page 12

Figure 3: The SCM Menu

Kurtzman/Page 13

Table 1: File Status Codes Used By Xcode

Code Meaning

<blank> This file is up to date.

? This file is not in the repository.

- This is a directory or a file within a directory that is not in the repository.

U This file is out of date. The repository contains a newer version of this file.

C The modifications in your working copy of this file conflict with the version

that is in the repository.

M This file has been modified.

A This file is scheduled to be added to the repository the next time you commit

all of your changes

R This file is scheduled to be deleted from the repository the next time you

commit all of your changes