0

I am writing an essay about a problem that I had in a program that I was creating, of course, I managed to fix the problem, but I am wondering how much detail I should put into describing the actual code. The audience that this essay is going to be presented to doesn't know anything about programming.

My question is, should I break down what little code I have in the essay into something more understandable to a random person that knows nothing about code, or should I keep the code the way it is?

I am very conflicted about this.

Also, I do describe what programming is in the essay, it goes into special detail about the programming languages that I used, which are HTML, CSS, and JavaScript.

I do want to give some more of the code, but I think that it won't be all that feasible to add more than what I have and have the readers still understand it.

Also, currently, I just have links at the bottom of the essay that takes you to the posts that are used in the essay.

Basically, I am asking, should I keep it the way it is or add more detail to the bits of code that are currently in it and possibly add some more?

Officer Erik 1K-88
  • 3
  • 3

1 Answers1

0

There is no point there being any words on the page the reader won’t understand. It wastes space, and may slow down or deter your reader from reading any further. If your audience won’t understand any code, then you should only include as much code as you are willing to explain line by line. That means very short blocks and eliding any lines the reader doesn’t need.

Of course, if you are able to explain how the code works with interesting analogies, you don’t need the code there at all. It’s up to you to decide if your audience may enjoy being taught the very basics of coding as they read, and whether the absolute basics of coding would be enough to get your points across anyway. If your story is mainly about syntax errors then the code may be of value to make a basic point, but if it’s about class inheritance, or recursion, then your essay will never get your audience to that level. In that case there’s little point teaching them the basics, and you should do it entirely with analogies.

mwo
  • 1,935
  • 13
  • 19