[UserStory] Clarify Usage Example documentation about use of Redistricting.jar

[DanielShermanSchool]

User Story

Essential components

• Title describes the story
• Stakeholder type is identified
• Outcome is described
• Rationale is explicit
• Acceptance criteria are verifiable and from the perspective of the stakeholder

Story

As a user
I want the usage example document create_and_display_region.md to clarify how to get and use the Redistricting.jar file
so that I know how to build and run the example.

Acceptance Criteria

• The document create_and_display_region.md describes why Redistricting.jar is needed.
• The document create_and_display_region.md describes how to acquire or build Redistricting.jar.
• The document create_and_display_region.md describes how Redistricting.jar is used in building and running the example.

Supporting Information

When first trying to build from the repository, I was trying to compile the Example1.java program described in create_and_display_region.md and was receiving "symbol not found" compilation errors. It is not clear upon first usage that Redistricting.jar and Example1.java need to be in the same folder, and/or Redistricting.jar is required to be able to use the product.

[jody]

Thanks for reporting this issue!
I've done some minor formatting and wordsmithing and checked the "Acceptance criteria" box.
Ready to be worked on so added to the project's "To Do".
---- Ooops, didn't save the changes. Need to go back and rework the text.
---- Updated the issue text.

[jody]

It looks like a simple expansion of the instructions might be sufficient.

Here is the current section the demonstrates the weakness.

redistricting/docs/examples/create_and_display_region.md

Lines 71 to 75 in dacf6fd

	### Sample Run
	The `Redistricting.jar` product was created using the build command
	```
	ant clean jar
	```

I propose that there be two sections, with headings
### Simple Build
and
### Sample Run

---

The Sample Build section would clarify that the Redistricting product resides in the jar file Redistricting.jar which must be in the classpaths used for compilation and execution of the example code.

The section would explain how to acquire the Redistricting.jar file. Although that currently requires building the file, it ultimately will also allow access through a direct download as described in User Story #171

• [UserStory] Add official release link to website #171

The section also reminds the reader that the Redistricting.jar file must be in the classpath of the Java compiler when the example source code is compiled.

My recommendation for this example is to show building the jar file followed by copying the jar file to the same directory as Example1.java.

% ant clean jar
.
.
.
% cp build/jar/Redistricting.jar theDirectoryContaining_Example1.java
% cd theDirectoryContaining_Example1.java
% javac -classpath Redistricting.jar:. Example1.java

---

The Sample Run section would clarify that the same jar file Redistricting.jar must be in the classpath of the Java runtime engine when the example class is executed.

% java -cp Redistricting.jar:. Example1

---

The existing Transcript section can remain as is.