Keeping Computer Science Writing Accessible and Eloquent

Question

This question is particularly aimed at descriptions and explanations of what is happening in a computer program, as well as any general advice or approaches for undertaking technical reports in Computer Science at both undergraduate and graduate levels.

You see, I am having particular difficulty in the best way to explain what is happening. As in, given any given program from a multi-agent system to a standard webservice, the best and most eloquent way to say exactly what is going on, the logic behind it and it's respective justifications.

Should I avoid saying class names? Avoid specifying methods? Keep referring to class variables and any particular references?

I'm banging my head against the wall at trying to keep a solid technical foundation and making it accessible to people of all backgrounds. Apologies for the rather vague question. Cheers.

Answer 1

What does your favourite CS textbook do in these cases? Whatever it is, do that.

Answer 2

My first question is "who is your audience?"

1. Technical
2. Non-Technical

And then within that, are there any particular commonalities that you can draw upon, so that you have a source for metaphors.

I personally like the writing style of Joel Spolsky:

http://www.joelonsoftware.com/

It's not a book, but he has a fairly down-to-earth feel, but only for at least somewhat technical people.

If it is for a technical paper with a highly technical audience, then lots of example code and analysis to tie it together.

If it's for a non-technical crowd, more on the metaphors and how it's applicable in the audience's life. You can cite references for the more technical observers to read up on more fully later.

I fact, that latter goes for any crowd. Programmers, too, know when they just read or were lectured on something that affects their lives - personal or professional.

And always include a little humor. :-)