Update build-matrix_5c062ead04286304a71cf455.md

[TomFern]

Proposed build matrix reference with examples

[markoa]

@TomFern Overall good first take but I'm sorry for not being clear in my initial instructions. The C and Java projects are let's say production examples which also contain some details that are not necessary for understanding the basics of how build matrix works on Semaphore. They make it harder, actually.

When reading the docs, users are usually in the middle of solving a concrete problem and generally speaking in a hurry. In a docs page that is not a "full-stack" tutorial, people want something they can copy & paste. So:

• Use as little words as possible to explain what you need.
• Simplest language.
• Simplest code snippets as possible, with zero noise.

So with that I think you need to rethink this page almost from scratch.

Some suggestions:

• Intro seems OK to me, probably not much editing is necessary.
• Let's have two examples, one with env vars and another which shows "Testing against multiple language versions". Let's pick Java for that, but write a minimal yml from scratch in which you set-version and then run java -version. Readers should know how to expand further for their project.
• Please run the YMLs that you write about on Semaphore yourself. You will then see that eg "the job will have been executed 9 times" is not correct, but that Semaphore runs 9 parallel jobs.

[TomFern]

@markoa thanks for the feedback. I'll rework doc and make the corrections.

[markoa]

Thanks, I think this is good to go for the first pass. We'll adjust further based on user feedback.