3-RCFinal Review
Getting Started with Your Review
I'm having a hard time deciding how much to explain here. I really don't want to explain anything, because I need to test if the webpages and instructions are useful and if they have the right information. Apologies if this is rude. Please feel free to e-mail me questions.
Please start at:
The download links from those pages are where to get the code. Do not get it from subversion, we have created packages for you.
Timeline
If possible, I would very much like to have this information ASAP. Ideally by Friday, but of course I will not reject feedback later. Please bear in mind that we hope to release the final code Monday.
What To Do
We are looking for language experts (and non-experts) to install RL-Glue, install the codec of their preference, and then build and run the mines-sarsa-example project in /examples. We'd like you to also look over the code and build system of the sample project. We'd love for you to poke around the code for the codec, but it's not required (don't want to burden you too much).
We are hoping that anything weird should jump out and be discovered this way before we do the final release.
Specifically we are looking for parts of the instructions that are confusing, or parts of the installation process that are not intuitive or complicated. We are in all cases looking for suggestions, hints, or vague ideas of how it could be better.
Expected time commitment is between one and two hours.
Obviously we are looking for anything obviously broken or misspecified. Failing those sort of overt errors, we are also looking for:
Installation
- Is the install process obvious/natural for a user of this language
- Is there a more automated or transparent process for installation that you have seen elsewhere?
- Are there any dependencies (root access, software dependencies) that any user (including an undergraduate student working on dept machines) may not have?
- Are there any steps that are implicitly expected and not explained in the instructions
- Any superfluous steps that are obviously not required?
Usage
- Are there any steps that would be a hassle if done on a regular basis? Like adding paths to the Matlab code or setting LD_LIBRARY_PATH in C/C++ if not installing as root?
- Can you think of how to resolve these hassles? Perhaps an explanation of how to update .bashrc or something of that nature?
Conventions
- Are file names and/or function/method names usually specified differently than we have for this particular language? For example, in Java we have tried to use camelCase, and in C we have used under_scores.
- Are comments written in the appropriate format? For example, in Java we use JavaDoc.
Documentation
- Anything that is explained poorly in the documentation
- Perhaps re-ordering would make the information more clear
- Perhaps a few more little snippets of information are required
- Different wording?
- Shorter examples?
No issue is too big or too small. Please be a firehouse of opinion, and we will sift and sort after (and maybe even follow up with you :P)
Making Comments To Us
If you have a Google Account of some sort, you can browse through the code, click a line you like or don't like, and the directly make a note in the file. The main RL-Glue branch to make comments in is here:
http://code.google.com/p/rl-glue/source/browse/#svn/branches/RL-Glue-3.0-RC-1-Final
The codecs branch is here:
http://code.google.com/p/rl-glue-ext/source/browse/#svn/branches/Codecs-for-RL-Glue-3.0-RC-1-Final
The way it works is that you go to one of those links, browse through the files, click lines that you don't like and make comments. When you are all finished, you will notice a link on the right hand side of the page that says "Publish Your Comments". You can make high level comments there. Then, when you submit them, I can see them and they will be linked to the specific lines.
More information is available here:
http://code.google.com/p/support/wiki/CodeReviews
You can also just send me e-mail: brian@tannerpages.com