Hello,

I've finally decided to make my own web and use it as portfolio so I can show my work to potential employers. It would be nice if I could get some feedback on the way I'm showing my work, so I won't give a bad impression. The site is still under construction, but I want to get some advice from you guys before I go on so I can correct my mistakes or improve things:

http://www.jgcamarasa.com/?page_id=8

Things I'm worried about:

• Is it getting too long? This specific project is pretty big and I still have some more parts to write about.
• Am I using the proper format? Is it okay to link to the source code the way I'm doing it or is it better to embed smaller parts on the page?
• Is the video demo actually helping? Is it a good practice?
• I'm not a native english speaker. Am I expressing myself correctly? (I'm aware there are some gramatical errors which I'll definitely clear up before going live.). Do my points get across or it just reads like a lot of gibberish?

Thank you so much for your time.

P.S: This is an unrelated question, but don't want to flood the board with topics. I'm going to apply to a job and I must provide an introduction letter and a covering letter and I can't figure the difference between the two. Any ideas? If it's wrong to ask the question here I'll edit the post and create a separate thread, thanks.

Things I'm worried about:

1. Is it getting too long? This specific project is pretty big and I still have some more parts to write about.
2. Am I using the proper format? Is it okay to link to the source code the way I'm doing it or is it better to embed smaller parts on the page?
3. Is the video demo actually helping? Is it a good practice?
4. I'm not a native english speaker. Am I expressing myself correctly? (I'm aware there are some gramatical errors which I'll definitely clear up before going live.). Do my points get across or it just reads like a lot of gibberish?

1> It is both too long and too short. It has a very large collection of external libraries, and is not clearly organized for review by a potential employer.

It is too long, because most if is clearly based on duplicating the code rather than writing useful functions. Some of the directories have five files that are exact duplicates with only a single string different between them. Good programmers don't repeat themselves in code, instead they either loop or write functions.

It is too short, because it doesn't seem to have much stuff that you actually wrote. There are over 200 files for external libraries, and very few files that look like you actually wrote them. Most of the ones you actually wrote look like they are under 10 lines of code, a small number are 20+ lines, but with all the obvious duplication between files it really doesn't impress me.

It is not clearly organized because I cannot tell what you did and what other libraries are doing. I have no idea what you actually wrote. My spot-check of the 200 libraries find copyright notices that show they were written by various companies and not by you. It took quite some time to find the code that you actually wrote.

2> The videos and links themselves are fine. That is, I can find the videos immediately and I can see the files. It is good to have both on a portfolio site.

While the project itself shows you can write code, the code is all python. Very few game companies are looking for python programmers.

Hello frob, thanks for your reply.

I think there's a misunderstanding here. The project that I'm showing is the engine itself, the C++ code. All files with the "Ax_" extension (AK for Alegria Kernel, AC for Alegria Component, etc) are mine, as you can see on the license header on each .hpp file. (Alegria.cpp & Alegria.hpp are mine too, of course). It has been 3 years of work on my part!

I did use external libraries, of course, here's the list:

• Box2D for physics simulation.
• Python for scripting.
• Soil for image loading.
• TinyXML for XML parsing.

The Python code is just examples of use of the API I expose to the actual user of my engine.

I don't know if you are aware of this, maybe it's me who misunderstood you!

Thanks for your reply!

EDIT: I also made the editor you see in the video and in the images (http://www.jgcamarasa.com/wp-content/uploads/2013/10/editor1.jpg). It's all part of the same project (as the editor is designed for the engine and it's seamlessly connected to it) but I thought it would be better to show it in a different page of my portfolio, which I will in the next days. You can find its source code here: http://code.google.com/p/alegria-editor/ .

This actually saddens me, because I couldn't even make clear what my project was about on my portfolio. Any tips on that?

About the readme.txt files you mean along the demos? Or in in the source code repository? On both maybe?

Thanks for your time.

I'm referring to putting a readme file in both the source code and repositiories because you are giving them out to potential employers who will be reviewing the code to judge your coding ability.

It doesn't need to be complex, just a simple statement telling what is in the package and where to find what they are looking for. .

The goal is that when someone (like me) wants to judge your programming abilities they can open the readme file, then immediately jump to whatever file the want.

My experience was that I downloaded your zip file and saw an executable and three directory trees. When I went looking for code the most meaty thing I could find was the "lib" directory which was filled with hundreds of what appeared to be third-party libraries. Then I want to the "demo" folders and found some uninspiring python scripts. After about ten minutes poking around and opening files at random, I decided I was done.

A much better experience would be to see a prominent readme file that told me exactly where to find your code and also briefly told what that code specifically does. Then I wouldn't need to open files at random, I could immediately jump to whatever you state is the most important files.

Gotcha, thanks for the advice frob.

Is it getting too long? This specific project is pretty big and I still have some more parts to write about.
Am I using the proper format? Is it okay to link to the source code the way I'm doing it or is it better to embed smaller parts on the page?
Is the video demo actually helping? Is it a good practice?
I'm not a native english speaker. Am I expressing myself correctly? (I'm aware there are some gramatical errors which I'll definitely clear up before going live.). Do my points get across or it just reads like a lot of gibberish?

A few comments:

1) I don't think it's too long per se, but I would try to reorganize it a bit better and create some spacing between sections and subsections. Have an overview with links to bookmarks further down the page, also have mini overviews for each section. I didn't have the same problem as frob looking at it, but clearly there is the possibility of confusion as right now it's a bit of a wall of text. Separating sections and having overviews might help break up the page visually better allowing people to process the information easier.

2) The video was cool. It might be better to embed the video on the page. I usually skim over text, but if I see an embedded video I'll be more inclined to watch it.

3) I wouldn't embed code on the page anymore than you are already doing. It would clutter the page too much. Just make it easy to view the source relevant to your sections for those that are interested.

Wow, that's spot on, very useful advice! Will definitely improve it based on your comments, thanks!