This is the IVOA edu IG's SVN repository, intended to work as a space to (ideally) cooperatively develop documentation, worked-out use cases, and the like. Subversion quick reference: http://www.cs.utexas.edu/users/flame/dev_info/svn_qref.html 1) Users of the repository ========================== READER: id the final user of the repository, only need the "checkout" grant CONTRIBUTOR: the user that provides tutorials and/or updates them, needs the "commit" permission (see sections 5 and 6 for guidelines on how to add new tutorials and update existing ones) TRANSLATOR: a special "reader" who offers himself to translate a tutorial in his own language. The translator should provide both source and pdf files of the translated titorial and contact the contact person written in the README of each tutorial in order to send him the translation to be uploaded 2) Document layout ================== Each piece of documentation should occupy a subdirectory of its own below trunk. It is recommended to have, below that subdirectory, the following structure: README -- a text file briefly describing what the tutorial is about. Please write this in English, and if at all possible give an email address where we may contact you. For multi-language documents, this also should contain the translation status (see section 3 for details) LICENSE -- this may sound silly, but you're making many people's lives easier if you dump in some text here that makes your contribution CC-0, CC-BY, or maybe CC-NC-BY. (see section 4 for details) res/ -- a subdirectory for resources common to all languages, e.g., detached files, sample data, and so on. Please refrain from keeping really big data here (a sensible size limit is a few Megabytes); if you *really* need this kind of thing, please try to host it somewhere else. en/ -- we would really appreciate if there were an English version of whatever materials you produce; the VO is international, and you're making re-use a whole lot easier if people can start from an English version. -- for language-specific files (i.e., usually the body text). 3) Translation Status ===================== For projects available in multiple languages, the README should contain translation status information. This is a simple map of languages to dates (which is not intended to be machine readable). It should look like this: en (master): 2012-12-24 de: 2012-10-30 it: 2012-10-30 cn: unknown The intention is that on development the master document, its change date gets changed. This serves as an informal version number -- using the date has the additional advantage that using svn log (or even, for suitable source formats, svn diff), translators can figure out what changes have been made. Translators having updated a language document would then copy the date of the respective master version to the line of their language. This, in particular, means that non-master dates are the one given in the master line, *not* the one at which the work was actually done. If development in another language overtakes the one of the previous master, this language would become the new master. Again, having non-English masters should be avoided. 4) Licenses =========== You are doing yourself and everyone else a favour if you apply a license to your work, and preferably either CC-BY or CC-0. Template files for these are in the LICENSES subdirectory of the repository. To apply one of those, go to your project directory and say svn copy \ https://svn.ari.uni-heidelberg.de/svn/edu/LICENSES/LICENSE.ccby \ LICENSE (or LICENSE.cc0 if that's what you prefer). Then fill out what's between less and greater signs (i.e., title and author). More details on the why, what, and how of Creative Commons is found on http://creativecommons.org 5) Add a new tutorial (for contributors) ======================================= - svn co - create a new folder (see section 7) - create README and LICENSE files - create a subfolder named "en" for the master tutorial sources - create eventually subfolders for each language the tutorial is available in (use ISO 3166-1 country codes: https://www.iso.org/obp/ui/#search) - create eventually the "res" subfolder for resource files common to all languages - svn commit -m (add a cooment on what you did) 6) Update an existing tutorial (for contributors) ================================================= - svn co "single folder" - work on it - update the README (vesion update is mandatory) - svn commit -m (add a cooment on what you did) 7) Naming ========= parent tutorial folder: - a project reference (if available, e.g. aida) - a short unique tutorial name (e.g. sky) - eventually a ìn incremental numbering for project reference - a-z_A-Z_0-9 character set only the tutorial files in the iso_countries subfolders should follow the parent folder name (e.g. aida_01_sky.doc/aida_01_sky.odt/aida_01_sky.pdf 8) On Version Control ===================== There's a top-level tags subdirectory to let you define releases that remain stable; the intent is that when referencing a tutorial, people can point to a tag (the http URL is public).