Contributing Tutorials

From ExternalWiki

We currently have a few Opus/UrbanSim tutorials, and would like to add significantly more. The Planned Tutorials has a list of planned and desired ones; we also hope to have tutorials contributed by the Opus/UrbanSim user community. Some tutorials, e.g. the Eugene Tutorial, are intended for UrbanSim beginners. But we definitely need tutorials on advanced topics as well. It's important to keep tutorials up-to-date! Ideally people who contribute a tutorial should be prepared to keep it up-to-date as well, but if this may be an issue please discuss it with us.

Tutorials can be formatted either as wiki pages (very lightweight), as latex documents (produces tutorials in the most useful form, but more heavy-weight to prepare), or using another word processing or document formatting program.

All tutorials are licensed under the GNU Free Documentation License.

Contributing Tutorials as Wiki Pages

You'll need to log in to our wiki system to edit it. If you don't have one already, request an account by sending email to help at urbansim dot org. Please also ask us if you have questions about what tutorials would be useful, what background to expect, and so forth.

Then go to the Tutorials page, add a link to your new tutorial in a reasonable place, and edit away. Since these tutorials are just on our wiki, rather than in a download file, in general they should apply to the current version of the system. Please note any system dependencies in the tutorial. (Right now we only have tutorials on the main download page; if we get some tutorials contributed as wiki pages we'll link those in.)

Contributing Tutorials using Latex

This approach produces tutorials as both pdf and html pages, and also causes the tutorials to be included in stable releases (in the zip file) -- so that if you have a tutorial that depends on a particular system version, it can accompany that release. However, it is more work to prepare them.

The latex source for these tutorials lives in the opus_docs subversion project, in the subdirectory opus_docs/tutorials.

To add a new tutorial, check out the opus_docs project from our subversion repository, and add the new tutorial in the tutorials/ directory. Tutorials use the Python documentation style files -- copies of these files are in the tutorials directory as well. The easiest way to use the appropriate style files is to copy the .tex file for an existing tutorial in that directory and modify it.

Caution: latex will get upset if you have an underscore in your file name (underscore is a latex special character). Use a hyphen instead.

When you check in the updated project, the source files for the tutorials are run through pdflatex to produce a pdf version, and also the latex2html converter to produce an html version. To get this to happen for your new tutorial as well, edit the build_docs.py file in the tutorials/ directory by adding your tutorial to the list:

modules = ["run-eugene-model", "lorenz-curve"]

Then, when you check in your changes to subversion, the pdf and html files for your new tutorial will be copied to the urbansim.org website. We will also include them in the zip file for the next stable release as pdf and html files.

The last step is to add these new files to the list of tutorials on the UrbanSim download page -- ask a CUSPA staff member to do this.

Contributing Tutorials Written using Another Word Processor

You can also prepare tutorials using another word processor, for example Microsoft Word.

The GNU Free Documentation License requires that if you post an "opaque" GFDL-licensed document on the web, you must also make available a "transparent" version, so that others can access and modify it. See the license for definitions of "opaque" and "transparent" -- but as specific examples, doc format, and pdf prepared from a *.doc document, are both opaque, since the pdf isn't editable (or at least would be very difficult to edit), and the doc format is only editable with a proprietary system.

So if you use Word, one way to satisfy this requirement would be to upload to the wiki both a pdf version and an rtf version of your tutorial -- the pdf version for easy reading and printing, the rtf version so that others can edit and revise it, without requiring proprietary software.