Writing a tutorial for an audience with some background knowledge

Question

At the moment, I am writing a JavaFX tutorial targeted at programmers with a solid grasp on Java. The idea is to give them an as-short-as-possible intro to JavaFX, focussing on the differences between Java and the JavaFX Scripting Language while at the same time skipping things which are identical in both languages.

The problem is: it's often hard to decide which needs to be explained in greater detail and which doesn't. Should I explain things like type inference, which is something not every Java programmer is aware of, or should I link to the appropriate Wikipedia article? Is it enough to present a source code example for showing things like invoking a function?

Any advice on that?

Greets, Oliver

Answer 1

Most writers tend to err on the side of caution because there's no real way of guaranteeing their audience's level. That said, there's no need to hand-hold through the bits that you can't be sure of - if progressed this far then they're not likely to feel threatened by needing a bit of research. I'd say that plenty of source code examples with a solid appendix should be good enough.

You might want to think about using little call-out boxes with more information on certain sections if you think it's necessary - make them look different to the normal body of the text so if a reader doesn't need to look at them they'll quickly spot them for what they are and can skip over them.