Start by reading this documentation

There is no bigger buzz kill when starting a new job than that moment when a tree load of written documentation is set before you and you are told to start there.

"Read this to give you an idea of how we work."

That is a ridiculous idea. Reading documentation to find out how people work is about as useful as reciting them a haiku in Japanese, when they first cross the workplace threshold. Actually, the haiku is much less boring.

When I started at Buzz Numbers last week, I was given a computer and a set of short videos to watch. These walked me through the main code solution and discussed different areas in details. They are not only introduction documentation but good refresher resources when you go in to an unknown section of the code.

I was happily coding within an hour of starting work, on my first day. The video docs gave a good push start and an easy reference point for when I asked myself where that thing was again.

Since Buzz Numbers has me sign an NDA on my first day, I won't be sharing any of their video documentation with you. It's not a new idea so there are many examples online of how this can be achieved. Thing is that it's usually big companies with big budgets that are doing this. I work for a start up and they did it without any major cost.

Simple. Inexpensive. Effective.

What more could you ask for? Try this at your workplace if you understand the pain a new starter feels.

Here is an example of Yahoo's YUI video documentation...

Geek Girl - For Better or Worse

Hey Geek Girl, you know your marriage is in trouble when...

0. You look to xkcd for relationship advice;

1. Waiting for a green build sends your heart racing more than seeing your husband;

2. You get more excited in bed at night when you hear emails arrive on your smart phone than when anything else pops up;

3. Comments on your latest blog post elicit more emotion than the man you married;

4. You have defined the majority of your conversation with your spouse as a regular expression punctuated with "uh huh" and "yep, I'm listening";

5. You stop reading his tweet stream and scroll past most of what he says. Before seeing him at home after work, you read the latest tweets so you can fake interest in his day;

6. He gets emoticons more than he get cuddles;

7. You "like" his facebook status without reading what it is and often have to explain that liking a negative one was in fact showing support. Oops;

8. The thought crosses your mind that selling your engagement ring diamond would easily cover a new MacBook Pro, iPad and phone;

9. His handwriting seems to look like line noise.

Choose Me. Choose Me.

There are all sorts of programs run in large companies these days to help people get through the working year, salary negotiation, conflict resolution and plain old peer support. They can be structured or informal but they are always there. No matter where I work, I set up a network inside and outside of work to make sure that there is a person to vent to; a person to bounce creative ideas off; someone to suggest how to resolve road blocks; etc..

Everyone needs some kind of support network in all aspects of their life. In this case, I am directly referring to the work place. Your job is something that you spend a whole lot of waking hours doing, so you have to make sure you do all that is in your power to make it a good experience. You'll notice I did not say "tolerable experience" because I don't think you should do a job that you don't like. If it is painful then fix it or leave it. Find a place you like to work and keep it that way. Making work a rewarding and enjoyable place to do is part of your full time job. Work at it. Work at doing the actual job well but also work on your relationships, your brand, your reputation and your purpose. It takes effort to do anything well. Make that effort enjoyable by finding a gang to help you negotiate the professional maze.

I would like to offer to be in the network of someone starting out as a software engineer. It doesn't matter how much experience you have or even if we are in the same technology. Female or male - it doesn't matter to me if it doesn't matter to you. If you are in Sydney and would like to build a graph of people who will help you out professionally then please contact me. I mean this on a one to one level.

What do I get out of it? I get to help out someone starting in the same way that so many great professionals stopped and helped me in my early career. I do this for a lot of younger people I have worked with and am sure that they would be happy to be references for me.

Let's start with a conversation about where you are going or where you want to be.

Contact me here by commenting on my blog or @damana on twitter.

How Software Loses My Trust

I have one word for you that is the most important concept in Information Technology: Trust

If users don't trust your product then they won't use it. It doesn't matter how many features you have or how many fancy schmancy algorithms are written in the latest whiz bang technology if a person uses your site and it behaves badly.

When you walk in to a financial institution, they will make it clear that the power of their brand and the price of their stock lies in the confidence their customers have in them. Especially important is the outward facing applications that they have on the Internet. Banks and Insurers are well aware of the importance of this. Even though they are huge mammoth organisations that do not always deal well with the tides of change, they will let that one guiding principal of being reliable and trustworthy guide their software development. This said, I mean mostly the facade of it in the very least. Then be careful what you pretend to be because you might just become that and finance computing is not that bad these days compared to other domains.

Why am I currently going on about trust in online software? Well, it all comes back to my old and true nemesis: Optus. For those of you who don't know the joke of a telecommunications market that we have in Australia, Optus is the second biggest telco in the game. Telstra is the biggest and still dominates since it had all it's infrastructure paid for when it was fully owned by the Federal Government and then privatised to make a quick $buck$. There are global players here like Vodaphone, Virgin Mobile and 3. No matter how innovative the imports try to be, the ruling duopoly holds them back with their market controlling behaviour and terrible customer service.

Recently, I've been led to believe Telstra service has improved but I'll have to wait to experience it again before calling it. As a mobile phone user with Optus, I have the right to throw as much mud as is acceptable, especially after the experience I had today.

This afternoon after 5pm, I received an automated call from Optus informing me that I had failed to pay my last two mobile phone bills for May and June. I was surprised at first and then remembered that I paid them on their website. You create an account on their website when you sign up for your phone account so that you can easily make payments online using your credit card. Over the almost 2 years of my phone contract, I have always paid using their website. It usually takes between 2-3 attempts to get the payment to go through and no matter how many times I ask them to save my credit card details for later use, they never manage to.

Each time I go to pay my bill, I login and go searching for the relevant bill paying screen. Of course one of the main headings is Bills in the left hand menu. Under that is a list of features and not one of them is for paying your bill. You instead have to click on the Bills heading to go to pay your bill. Tricky but I learned that after about 6 months of wanting to commit homicide on any random member of their usability team. Ahh, the delusional assumption that they even have one is still strong in me.

Once the page required to pay my bill is found in the rat's nest that is their website, I re-enter all my card details and choose to pay. You can't choose how much you want to pay. They give you that number and you just pay it. The invoice amount is updated once a month and if you have already paid but it didn't register then they just add it to the next total. I learned to ignore that too. Once I paid twice the amount and they wouldn't even reimburse but instead held it over for my next invoice. Yes, their refused to pay back money that they should never even have taken.

Then I pay until they accept the payment. Like I said, after about 3 tries. They give me a receipt number and my final assumption is that the bill is successfully paid. Actually, that assumption is based on the text on the screen that says something about your bill being successfully paid.

Several months later, an automated dialing machine with a rude message accusing me of being a bad customer who never pays is placed to my mobile phone after working hours.

At least they are consistent but the one thing that Optus does not have is my trust. I lack trust in their billing system, their payment gateway, their phone service and even snigger at their advertising. They DON'T care what I think. I'm stuck in a two year contract with them that promises I'll pay my $83.50 per month for my phone service. Obviously none of that money goes to their IT department. We instead pay for that with blood.

When the time comes to find a new provider for my mobile phone, I'm considering dropping back to tin cans and string. It certainly won't be with Optus because I can't trust them and I don't want a relationship with someone I can't trust.

iPad-ing Across the Universe

I got me an iPad :)

C# 4 Last Minute Additions

Update: I'm being very anti-Microsoft at the moment because they make it too expensive for me to get an MSDN license to develop at home. In the past, I've been a big fan but I'm going to defect if they continue down the money or nothing path. Until they stop excluding me from their expensive community, I shall sulk and ridicule them. Please read and have a giggle. It's meant in jest.



I love reading Eric Lippert's blog because he is great at explaining complex ideas in an easy way. That is something severely lacking online. He also dishes the news on my latest reading obsession... C# 4.

They have managed to slip in a few extra features last minute in to the next version of the language. He describes them in more details here. The one's I thought were cute and make the language a little more interesting are the goes to --> and is approached by <-- operators used in loop conditions.

The examples given on his blog show them being used like this:

int x = 10;
// this is read "while x goes to zero"
while (x --> 0)
{
Console.WriteLine("x = {0}", x);
}

int x = 10;
// this is read "while zero is approached by x"
while (0 <-- x) { Console.WriteLine("x = {0}", x); }

Interestingly, when I mentioned the last minute additions to a colleague she commented that she hopes they implemented them properly. In C# 3 they snuck in partial methods and auto-properties which I wouldn't want to live without (although I am in Java-land at the moment).

I'm excited about C# 4. Now I just have to get Microsoft to give me a reasonably priced MSDN license for an individual who isn't a student, a company or a start-up. Market gap.

A recent email I sent to a friend who has started automated testing

Here is a quick email I threw together for a friend who has started writing automated tests and asked if there is a reason to have lots of different kinds of tests covering the same area. Yes, it's simplistic and I'm sure a bunch of ThoughtWorkers would kick me and say it is better explained in other ways but I think this is a good summary. In case it helps others, here it is...



OK, this is the way I structure testing of an application. This works when the tests are written retrospectively or if the application is written in a test driven manner.

There are three types of tests:

1. Functional tests - UI testing that uses the terms of the users/business. You'll see tools like Selenium with junit/nunit/rspec used at this level. Functional areas of the application are tested in a similar workflow to what I user would use. Happy path comes in here for primary workflows. Deliberate error (validation and business logic) and exception testing at the highest level occur now;
   
2. Integration tests - these tests are used when you are plugging all the bits of your system together. Bits can mean layers, components within a layer, or dependencies outside of your system (third party web services, etc...). The point of this is a test interfaces and APIs that are public to the component or application parts. You test input and output in a black box way. Again, with all good data and then causing errors and exceptions;
3. Unit tests - These tests are the very specific low level tests that check that a unit of functionality is working. This can be at a class level, library or component. You'll see mocking frameworks used here to imitate data sources or connecting systems. At this point, you do not want to be distracted by the possibility of functionality external to this unit causing issues so it doesn't talk to anything and gets all input or directs all output to mocked objects.

The reason for the three layers individually is explained above in each point. The reason you do them together is that with continuous integration and thorough test suites, you can easily track down where an error is occurring and focus in on the area of concern. All these tests should be used together.

This is a starting point and written at a high-level. Ask me if you need it clarified further.